Ramune

# Ramune

## Philosophy

Ramune is a marble soda works for the screen. It dresses an interface like a flat gouache poster printed in a risograph register: a deep saturated soda-teal ground carries the page, milky candy-colour planes float as flat surfaces, and one glass bead of refracted light follows every live state. It keeps the dew-fresh sweetness of its source while reversing its milky-white default — here the saturated colour is the page, not a tint on a blank sheet.

### Values

- Colour as ground: the saturated teal air carries the work; colour is the page, never a wash on white.
- One bead leads: a single glass-bead of light marks the one live moment in any group; everything else stays calm.
- Aplat planes: surfaces are gouache-flat with hard stops, depth from tone and inset dew-light, never heavy shadow.
- Reading honesty: all body text sits on solid milky surfaces at high contrast, never on candy colour or transparency.
- Disciplined sweetness: youthful and fresh, but modular and quiet — a poster, not a toy.

### Anti-Values

- Defaulting to a white or milky ground — the look this language deliberately reverses.
- Rainbow gradients, neon glow, or more than three accent families.
- Gummy toy controls, mascots, oversized bubbles, or cartoon stickers.
- Accent edges on cards, nested cards, heavy drop shadows, or body text over blur.

## Tokens

### Colors

| Name | Value |
|------|-------|
| bg | `#0E5C66` |
| bg_deep | `#0A4750` |
| surface | `#FCF3EE` |
| surface_2 | `#F4E3DC` |
| text | `#1C3338` |
| muted | `#5C7176` |
| on_ground | `#EAFBFB` |
| on_ground_muted | `#9FD3D6` |
| accent | `#E8657F` |
| on_accent | `#FFFFFF` |
| soda | `#6FB7D6` |
| mint | `#57C99B` |
| border | `rgba(28,51,56,0.12)` |
| success | `#57C99B` |
| warning | `#E0A23C` |
| error | `#E8657F` |
| info | `#6FB7D6` |

### Typography

- **Base Size**: 17px
- **Body Font**: Zen Maru Gothic
- **Heading Font**: Fraunces
- **Mono Font**: IBM Plex Mono
- **Heading Weight**: 600
- **Heading Transform**: none
- **Letter Spacing**: -0.02em
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,500;9..144,600&family=Zen+Maru+Gothic:wght@400;500;700&family=IBM+Plex+Mono:wght@500&display=swap

### Radii

- **None**: 0
- **Sm**: 16px
- **Md**: 24px
- **Lg**: 24px
- **Full**: 9999px

### Shadows

- **Sm**: 0 1px 0 rgba(255,255,255,0.9) inset, 0 4px 10px rgba(10,30,34,0.10)
- **Md**: 0 1px 0 rgba(255,255,255,0.92) inset, 0 10px 26px rgba(10,30,34,0.14)
- **Lg**: 0 1px 0 rgba(255,255,255,0.95) inset, 0 22px 50px rgba(10,30,34,0.20)
- **Bead**: 0 0 0 2px rgba(255,255,255,0.85) inset, 0 2px 6px rgba(28,51,56,0.20)

### Spacing

- **Base**: 4px
- **Scale**: ["6px","12px","20px","32px","52px","84px"]

### Surfaces

- **Ground**: deep saturated soda-teal, the page itself
- **Card**: milky candy paper plane floating on the ground, 24px radius, inset dew-light
- **Rail**: fizz-deep teal for navigation and full-bleed bands

### Borders

- **Default Width**: 1px
- **Style**: hairline only
- **Character**: near-invisible tonal hairlines; never an accent edge on a card; depth comes from tone and inset light

### Motion

- **Duration**: 200ms
- **Easing**: cubic-bezier(.2,.7,.2,1)
- **Philosophy**: a small settling fizz: opacity and 2px translate only, no bounce; reveals are scroll-triggered and respect prefers-reduced-motion

## Rules

### Composition

Saturated teal ground carries the page; milky candy paper planes float on it. The landing opens on a full-bleed gouache hero with a teal panel anchoring the headline copy. Below, sections alternate layout families — staggered poster planes, a split reading card, a horizontal bottle shelf, a centred quote band — never a repeating grid of equal cards.

### Hierarchy

Hierarchy comes from type scale, weight, and air first; one glass bead marks the single live moment per group. Primary actions are quiet lychee pills with a catch-light bead; everything else recedes to milky paper. Long-form text always gets the highest contrast.

### Density

Low-to-medium density with generous gutters; the page reads like a printed poster, not a component inventory. Data-rich surfaces group into soft labelled sections.

### Signature

The glass-bead: a radial-gradient marble (white catch-light, accent body, dark rim, inset white ring) that anchors active state, status, primary buttons, and the heads of meters and bars. Carbonation reads as flat hard-stop colour planes tipped with a bead.

## Layout

### Grid

12-column max-1180px contained content on a full-bleed teal ground; full-bleed hero spans 100vw, full-bleed bands use fizz-deep teal.

### Whitespace

Generous; always pad above titles; let the teal air remain open.

### Density

low-to-medium

### Responsive

Stack to a single column on mobile, hide non-essential nav and table columns, never overflow horizontally; cap and centre on ultra-wide while only the hero spans 100vw. minmax(0,1fr) columns and min-width:0 children everywhere.

### Breakpoints

- **Mobile**: 390px
- **Tablet**: 760px
- **Desktop**: 1024px
- **Wide**: 1700px

## Guidance

### Do

- Start from the saturated teal ground; let colour carry the page.
- Use one glass bead per group for the live state; keep the rest milky and quiet.
- Style every form control explicitly — selects, switch knobs, focus rings — never browser defaults.
- Keep all body text on solid milky surfaces at AA contrast.
- Alternate layout families between sections; pad above every title.

### Don't

- Don't default to a white or milky ground.
- Don't use gradients as decoration, neon, or more than three accent families.
- Don't put an accent edge on a card, nest cards, or lean on heavy shadow.
- Don't add emoji or symbol glyphs to buttons or copy — use CSS/SVG primitives like the bead.

### Accessibility

Maintain WCAG AA: #1C3338 on milky surfaces, #EAFBFB on the teal ground. Beads and accent colour never carry information alone — always paired with text. Targets at least 44px high; focus uses a 2px soda ring with offset; reduced-motion users get instant state changes.

## Imagery Direction

### Pairs With

sirop

### Summary

Flat opaque gouache poster prints in a risograph register: hard-stop candy-colour planes, fine paper grain, and glossy round bead highlights catching the light. Subjects are rendered full-frame on the saturated teal-and-candy palette, never on white.

### Subjects

- marble soda bottles and the glass marble
- fizzing bubbles and refracted light
- fresh fruit and syrup pours
- bottling-works objects and crates
- still-life soda counter scenes

### Usage

One full-bleed hero per landing in the Aplat technique; below the hero, return to flat CSS planes. Hero composed with a calmer colour field for an overlaid press block. End every prompt with: NO text, NO letters, NO logos.

---
version: "alpha"
name: "Ramune"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  bg: "#0E5C66"
  bg_deep: "#0A4750"
  surface: "#FCF3EE"
  surface_2: "#F4E3DC"
  text: "#1C3338"
  muted: "#5C7176"
  on_ground: "#EAFBFB"
  on_ground_muted: "#9FD3D6"
  accent: "#E8657F"
  on_accent: "#FFFFFF"
  soda: "#6FB7D6"
  mint: "#57C99B"
  success: "#57C99B"
  warning: "#E0A23C"
  error: "#E8657F"
  info: "#6FB7D6"
typography:
  headline-lg:
    fontFamily: "Fraunces"
    fontSize: "2.075rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  headline-md:
    fontFamily: "Fraunces"
    fontSize: "1.66rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: "Zen Maru Gothic"
    fontSize: "17px"
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: "-0.02em"
  label-md:
    fontFamily: "IBM Plex Mono"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
rounded:
  none: "0px"
  sm: "16px"
  md: "24px"
  lg: "24px"
  full: "9999px"
spacing:
  base: "4px"
  xs: "6px"
  sm: "12px"
  md: "20px"
  lg: "32px"
  xl: "52px"
  2xl: "84px"
components:
  color-reference-bg:
    backgroundColor: "{colors.bg}"
  color-reference-bg_deep:
    backgroundColor: "{colors.bg_deep}"
  color-reference-surface:
    backgroundColor: "{colors.surface}"
  color-reference-surface_2:
    backgroundColor: "{colors.surface_2}"
  color-reference-text:
    backgroundColor: "{colors.text}"
  color-reference-muted:
    backgroundColor: "{colors.muted}"
  color-reference-on_ground:
    backgroundColor: "{colors.on_ground}"
  color-reference-on_ground_muted:
    backgroundColor: "{colors.on_ground_muted}"
  color-reference-accent:
    backgroundColor: "{colors.accent}"
  color-reference-on_accent:
    backgroundColor: "{colors.on_accent}"
  color-reference-soda:
    backgroundColor: "{colors.soda}"
  color-reference-mint:
    backgroundColor: "{colors.mint}"
  color-reference-success:
    backgroundColor: "{colors.success}"
  color-reference-warning:
    backgroundColor: "{colors.warning}"
  color-reference-error:
    backgroundColor: "{colors.error}"
  color-reference-info:
    backgroundColor: "{colors.info}"
  button-primary:
    backgroundColor: "{colors.accent}"
    textColor: "#000000"
    typography: "{typography.label-md}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"
  card-surface:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"
  input-default:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text}"
    rounded: "{rounded.md}"
    height: "44px"
---

# Ramune

## Overview

Ramune is a marble soda works for the screen. It dresses an interface like a flat gouache poster printed in a risograph register: a deep saturated soda-teal ground carries the page, milky candy-colour planes float as flat surfaces, and one glass bead of refracted light follows every live state. It keeps the dew-fresh sweetness of its source while reversing its milky-white default — here the saturated colour is the page, not a tint on a blank sheet.

### Values

- Colour as ground: the saturated teal air carries the work; colour is the page, never a wash on white.
- One bead leads: a single glass-bead of light marks the one live moment in any group; everything else stays calm.
- Aplat planes: surfaces are gouache-flat with hard stops, depth from tone and inset dew-light, never heavy shadow.
- Reading honesty: all body text sits on solid milky surfaces at high contrast, never on candy colour or transparency.
- Disciplined sweetness: youthful and fresh, but modular and quiet — a poster, not a toy.

### Anti-Values

- Defaulting to a white or milky ground — the look this language deliberately reverses.
- Rainbow gradients, neon glow, or more than three accent families.
- Gummy toy controls, mascots, oversized bubbles, or cartoon stickers.
- Accent edges on cards, nested cards, heavy drop shadows, or body text over blur.

## Colors

Use the YAML color tokens as the normative palette. The prose below names the roles agents should preserve when generating UI.

| Token | Value |
|-------|-------|
| bg | `#0E5C66` |
| bg_deep | `#0A4750` |
| surface | `#FCF3EE` |
| surface_2 | `#F4E3DC` |
| text | `#1C3338` |
| muted | `#5C7176` |
| on_ground | `#EAFBFB` |
| on_ground_muted | `#9FD3D6` |
| accent | `#E8657F` |
| on_accent | `#FFFFFF` |
| soda | `#6FB7D6` |
| mint | `#57C99B` |
| success | `#57C99B` |
| warning | `#E0A23C` |
| error | `#E8657F` |
| info | `#6FB7D6` |

## Typography

- **Headline-Lg**: Fraunces, 2.075rem, weight 700, line-height 1.1.
- **Headline-Md**: Fraunces, 1.66rem, weight 600, line-height 1.15.
- **Body-Md**: Zen Maru Gothic, 17px, weight 400, line-height 1.5.
- **Label-Md**: IBM Plex Mono, 0.75rem, weight 600, line-height 1.

## Layout

### Spacing Tokens

- **Base**: `4px`
- **Xs**: `6px`
- **Sm**: `12px`
- **Md**: `20px`
- **Lg**: `32px`
- **Xl**: `52px`
- **2xl**: `84px`

### Grid

12-column max-1180px contained content on a full-bleed teal ground; full-bleed hero spans 100vw, full-bleed bands use fizz-deep teal.

### Whitespace

Generous; always pad above titles; let the teal air remain open.

### Density

low-to-medium

### Responsive

Stack to a single column on mobile, hide non-essential nav and table columns, never overflow horizontally; cap and centre on ultra-wide while only the hero spans 100vw. minmax(0,1fr) columns and min-width:0 children everywhere.

### Breakpoints

- **Mobile**: 390px
- **Tablet**: 760px
- **Desktop**: 1024px
- **Wide**: 1700px

## Elevation & Depth

### Shadows

- **Sm**: 0 1px 0 rgba(255,255,255,0.9) inset, 0 4px 10px rgba(10,30,34,0.10)
- **Md**: 0 1px 0 rgba(255,255,255,0.92) inset, 0 10px 26px rgba(10,30,34,0.14)
- **Lg**: 0 1px 0 rgba(255,255,255,0.95) inset, 0 22px 50px rgba(10,30,34,0.20)
- **Bead**: 0 0 0 2px rgba(255,255,255,0.85) inset, 0 2px 6px rgba(28,51,56,0.20)

## Shapes

### Rounded

- **None**: `0px`
- **Sm**: `16px`
- **Md**: `24px`
- **Lg**: `24px`
- **Full**: `9999px`

### Surfaces

- **Ground**: deep saturated soda-teal, the page itself
- **Card**: milky candy paper plane floating on the ground, 24px radius, inset dew-light
- **Rail**: fizz-deep teal for navigation and full-bleed bands

### Borders

- **Default Width**: 1px
- **Style**: hairline only
- **Character**: near-invisible tonal hairlines; never an accent edge on a card; depth comes from tone and inset light

## Components

### Composition

Saturated teal ground carries the page; milky candy paper planes float on it. The landing opens on a full-bleed gouache hero with a teal panel anchoring the headline copy. Below, sections alternate layout families — staggered poster planes, a split reading card, a horizontal bottle shelf, a centred quote band — never a repeating grid of equal cards.

### Hierarchy

Hierarchy comes from type scale, weight, and air first; one glass bead marks the single live moment per group. Primary actions are quiet lychee pills with a catch-light bead; everything else recedes to milky paper. Long-form text always gets the highest contrast.

### Density

Low-to-medium density with generous gutters; the page reads like a printed poster, not a component inventory. Data-rich surfaces group into soft labelled sections.

### Signature

The glass-bead: a radial-gradient marble (white catch-light, accent body, dark rim, inset white ring) that anchors active state, status, primary buttons, and the heads of meters and bars. Carbonation reads as flat hard-stop colour planes tipped with a bead.

## shadcn/ui Usage

When the target app uses shadcn/ui, copy DESIGN.md with shadcn instead of the plain DESIGN.md. It contains the same Katagami design-language source plus the shadcn/ui primitives, imports, theme variables, component recipes, and preview-shot guidance.

DESIGN.md with shadcn: `/language/en-019ef67c-3c45-7582-ad60-828821a64e88/DESIGN.with-shadcn.md`.

The shadcn page also exposes optional machine-readable files for automation, but the human-facing handoff is DESIGN.md with shadcn.

Install recommended primitives with `npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table`.

Use these primitives in shadcn apps:
- button
- card
- input
- textarea
- select
- dialog
- sheet
- tabs
- badge
- separator
- checkbox
- switch
- slider
- tooltip
- dropdown-menu
- table

Implementation rule for agents: import shadcn primitives from `@/components/ui/*`, apply the generated CSS variables first, then compose the language-specific recipes from the companion MD. Katagami remains the source of truth; shadcn names are the implementation surface.

## Do's and Don'ts

- Do Start from the saturated teal ground; let colour carry the page.
- Do Use one glass bead per group for the live state; keep the rest milky and quiet.
- Do Style every form control explicitly — selects, switch knobs, focus rings — never browser defaults.
- Do Keep all body text on solid milky surfaces at AA contrast.
- Do Alternate layout families between sections; pad above every title.
- Don't Don't default to a white or milky ground.
- Don't Don't use gradients as decoration, neon, or more than three accent families.
- Don't Don't put an accent edge on a card, nest cards, or lean on heavy shadow.
- Don't Don't add emoji or symbol glyphs to buttons or copy — use CSS/SVG primitives like the bead.

### Accessibility

Maintain WCAG AA: #1C3338 on milky surfaces, #EAFBFB on the teal ground. Beads and accent colour never carry information alone — always paired with text. Targets at least 44px high; focus uses a 2px soda ring with offset; reduced-motion users get instant state changes.

## Imagery Direction

### Pairs With

sirop

### Summary

Flat opaque gouache poster prints in a risograph register: hard-stop candy-colour planes, fine paper grain, and glossy round bead highlights catching the light. Subjects are rendered full-frame on the saturated teal-and-candy palette, never on white.

### Subjects

- marble soda bottles and the glass marble
- fizzing bubbles and refracted light
- fresh fruit and syrup pours
- bottling-works objects and crates
- still-life soda counter scenes

### Usage

One full-bleed hero per landing in the Aplat technique; below the hero, return to flat CSS planes. Hero composed with a calmer colour field for an overlaid press block. End every prompt with: NO text, NO letters, NO logos.

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "ramune",
  "type": "registry:theme",
  "title": "Ramune shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#0E5C66",
      "foreground": "#1C3338",
      "card": "#FCF3EE",
      "card-foreground": "#1C3338",
      "popover": "#FCF3EE",
      "popover-foreground": "#1C3338",
      "primary": "#1C3338",
      "primary-foreground": "#ffffff",
      "secondary": "#f4f4f5",
      "secondary-foreground": "#111111",
      "muted": "#5C7176",
      "muted-foreground": "#1C3338",
      "accent": "#E8657F",
      "accent-foreground": "#ffffff",
      "destructive": "#E8657F",
      "border": "rgba(28,51,56,0.12)",
      "input": "rgba(28,51,56,0.12)",
      "ring": "#E8657F",
      "chart-1": "#1C3338",
      "chart-2": "#f4f4f5",
      "chart-3": "#E8657F",
      "chart-4": "#57C99B",
      "chart-5": "#E0A23C",
      "sidebar": "#FCF3EE",
      "sidebar-foreground": "#1C3338",
      "sidebar-primary": "#1C3338",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#6FB7D6",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "rgba(28,51,56,0.12)",
      "sidebar-ring": "#E8657F",
      "radius": "24px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#1C3338",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#E8657F",
      "accent-foreground": "#ffffff",
      "destructive": "#E8657F",
      "border": "#303642",
      "input": "#303642",
      "ring": "#E8657F",
      "chart-1": "#1C3338",
      "chart-2": "#f4f4f5",
      "chart-3": "#E8657F",
      "chart-4": "#57C99B",
      "chart-5": "#E0A23C",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#1C3338",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#E8657F",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#E8657F",
      "radius": "24px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019ef67c-3c45-7582-ad60-828821a64e88",
    "slug": "ramune",
    "componentManifest": [
      "button",
      "card",
      "input",
      "textarea",
      "select",
      "dialog",
      "sheet",
      "tabs",
      "badge",
      "separator",
      "checkbox",
      "switch",
      "slider",
      "tooltip",
      "dropdown-menu",
      "table"
    ],
    "installCommand": "npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table",
    "nativeTokenNames": {
      "colors": [
        "accent",
        "bg",
        "bg_deep",
        "border",
        "error",
        "info",
        "mint",
        "muted",
        "on_accent",
        "on_ground",
        "on_ground_muted",
        "soda",
        "success",
        "surface",
        "surface_2",
        "text",
        "warning"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "heading_transform",
        "heading_weight",
        "letter_spacing",
        "mono_font"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm"
      ],
      "shadows": [
        "bead",
        "lg",
        "md",
        "sm"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "surfaces": [
        "card",
        "ground",
        "rail"
      ],
      "borders": [
        "character",
        "default_width",
        "style"
      ],
      "motion": [
        "duration",
        "easing",
        "philosophy"
      ]
    }
  }
}
```