back to gallery
design language·storybook-page-turn

Storybook Page Turn

A portable design language for agents: download the markdown first, then inspect the preview, tokens, and rules as needed.

Download DESIGN.md

Portable DESIGN.md source of truth for most agents and apps.

the spec

specification

philosophy
summary
Storybook Page Turn is a child-centered interface language for sequential visual storytelling: it treats screens like picture-book spreads where composition, cropped illustration panels, and the emotional beat of the next page carry as much meaning as the words. It borrows from picture-book mechanics rather than decorative nostalgia: page turns create anticipation, image and text clarify each other, full-bleed moments contrast with quiet vignettes, and palette shifts mark changes in feeling. The result is warm, legible, museum-aware, and designed for children and caregivers to understand at a glance without flattening the artwork into a generic kid app.
values
Sequential pacingImage-text partnershipWarm clarityPage-turn emotionChild-scale affordancesCraft without clutter
anti-values
×Cartoon chaos×Component catalog thinking×Soft low-contrast pastels×Generic edtech templates
tokens
colors17 items
primary
#000000
secondary
#7A3E1D
accent
#F5B82E
background
#FFFFFF
surface
#FFFFFF
text
#000000
muted
#5F5A52
border
#000000
error
#B3261E
success
#1F7A3A
warning
#B26B00
info
#2457A6
paper_warm
#FFF6E2
ink_soft
#24211E
sky_page
#D9EBFF
leaf_page
#DDEECF
coral_page
#FFDDD2
typography10 items
heading font
Fraunces
body font
IBM Plex Sans
mono font
IBM Plex Mono
base size
16px
scale ratio
1.25
line height
1.5
letter spacing
-0.02em
google fonts url
https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600;9..144,700&family=IBM+Plex+Mono:wght@500;600&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap
sizes
caption 12px·body 16px·lead 20px·h3 25px·h2 32px·h1 48px
weights
regular 400·medium 500·semibold 600·bold 700
spacing2 items
base
8px
scale
4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px, 96px
radii5 items
none
0px
sm
16px
md
16px
lg
24px
full
9999px
shadows3 items
sm
3px 3px 0 #000000
md
6px 6px 0 rgba(0,0,0,0.92)
lg
10px 10px 0 rgba(0,0,0,0.86)
surfaces3 items
treatment
paper
card style
white printed-paper panels with black ink borders, light paper grain, and controlled warm accent washes
bg pattern
noise
borders4 items
default width
2px
accent width
4px
style
solid
character
crisp black ink outlines that define every story page, card, and control with friendly publication clarity
motion3 items
duration
180ms
easing
cubic-bezier(0.2, 0.8, 0.2, 1)
philosophy
snappy page-turn motion: small lifts and slides suggest paper handling without distracting animation
rules
composition
Use a spread-first composition with a dominant two-page stage, a visible gutter, and an intentional alternation between full-bleed story art and small supporting vignettes. Keep primary controls in the lower or side margin like reading aids, not floating SaaS chrome. Reserve the golden accent for current page, next action, and emotional emphasis. Build narrative direction left-to-right with arrows, tabs, or page numbers. Use white as the main background so warm color blocks read as illustrations rather than UI wallpaper. Keep each cluster visually complete enough that a child can infer what to do from proximity and scale.
hierarchy
Fraunces headlines create story-title hierarchy; IBM Plex Sans handles readable instructions; IBM Plex Mono is limited to page numbers, spread codes, and tiny production labels. The largest illustration or panel always marks the current emotional beat. Captions are short and ribboned. Controls are high-contrast, 44px or taller, and grouped by story task rather than component type.
density
Moderate density with generous page margins and compact captions. The interface should feel like a working picture-book spread: enough tools to plan the story, but never so many equal cards that the narrative sequence disappears.
signature patterns
A CSS center-gutter pseudo-element divides the main stage into left and right pages, including small binding dots to make the spread structure visible.Cards and buttons use 2px black borders plus translate-on-hover with offset box-shadow, creating a printed cutout lift instead of soft SaaS depth.Caption ribbons are absolutely positioned pill labels that overlap image panels and use IBM Plex Mono uppercase page language.Full-bleed illustration panels use simple CSS shape scenery with high value contrast, while smaller vignette cards use the same border system at reduced scale.Page-turn tabs use one golden accent fill and triangular folded-corner pseudo-elements to mark current and upcoming emotional beats.
layout
density
Moderate child-centered density: large reading targets, strong contrast, and enough whitespace for adults and children to point, scan, and discuss the story sequence together.
grid
Desktop uses a 12-column max-width 1280px stage with a 32px gutter; the central spread spans 8 columns and the planning rail spans 4. Inside the spread, a two-column page grid is divided by a 16px center gutter. Tablet collapses to an 8-column flow with the planning rail below. Mobile becomes a single-column stack with the gutter rendered as a horizontal page seam.
breakpoints
desktop
1200px and up
tablet
768px to 1199px
mobile
480px and below
whitespace
Whitespace behaves like paper margin: 24px minimum around cards, 32px around the main spread, and 48px around hero areas on desktop. Never fill every corner; leave breathing room where page turns need anticipation.
responsive
At 1024px reduce the outer grid to one main column plus compact rail. At 768px stack the spread and rail. At 480px convert the two-page spread into sequential full-width panels and make all controls full-width.
guidance
do
  • Design screens as narrative spreads with a clear current beat, next beat, and supporting vignettes.
  • Use pure white backgrounds, black ink text, and the golden accent sparingly for page-turn emphasis.
  • Keep letter-spacing at -0.02em across headings, body, labels, and controls.
  • Give every important surface a visible 2px black border and consistent 16px or 24px radius.
  • Place captions so they overlap images or panels, reinforcing image-text interplay.
  • Use full-bleed illustration areas for emotional reveals and smaller vignette cards for setup details.
  • Make controls at least 44px high with obvious hover, focus, disabled, and selected states.
  • Shift warm supporting colors by scene emotion, but keep one accent color as the UI signal.
avoid
  • Do not use pastel page backgrounds, rainbow accents, gradient text, or crypto-style gradient buttons.
  • Do not build a component catalog with sections named controls, data, or feedback.
  • Do not use Poppins, Montserrat, DM Sans, Space Grotesk, or novelty cartoon fonts.
  • Do not mix random border radii; stay within 0px, 16px, 24px, and 9999px.
  • Do not let decorative illustration reduce contrast or obscure text.
  • Do not make all cards the same size; picture-book pacing needs contrast between reveal and vignette.
  • Do not rely on animation to explain structure; the page sequence must be clear when static.
katagami spec
# Storybook Page Turn

## Philosophy

Storybook Page Turn is a child-centered interface language for sequential visual storytelling: it treats screens like picture-book spreads where composition, cropped illustration panels, and the emotional beat of the next page carry as much meaning as the words. It borrows from picture-book mechanics rather than decorative nostalgia: page turns create anticipation, image and text clarify each other, full-bleed moments contrast with quiet vignettes, and palette shifts mark changes in feeling. The result is warm, legible, museum-aware, and designed for children and caregivers to understand at a glance without flattening the artwork into a generic kid app.

### Values

- {"name":"Sequential pacing","explanation":"Every screen should imply before and after. Panels, page tabs, progress markers, and cropped scenes create the feeling of a spread in motion rather than an isolated dashboard."}
- {"name":"Image-text partnership","explanation":"Text blocks are short, caption-like, and positioned as companions to images. Illustrations do narrative work; copy points, labels, and confirms rather than overexplaining."}
- {"name":"Warm clarity","explanation":"The palette is warm and inviting but not pastel or low contrast. White paper fields, black ink text, and one sunny accent keep accessibility and focus intact."}
- {"name":"Page-turn emotion","explanation":"Color temperature and surface scale shift between calm planning areas and high-energy reveal areas, echoing how picture books use page turns to change mood."}
- {"name":"Child-scale affordances","explanation":"Controls are large, plain-spoken, and tactile. Roundness is consistent, borders are visible, and actions are understandable from shape and placement."}
- {"name":"Craft without clutter","explanation":"Paper grain, ink rules, and sticker-like cutouts appear as disciplined structural devices, never as a scrapbook of random decorations."}

### Anti-Values

- {"name":"Cartoon chaos","explanation":"Avoid rainbow palettes, novelty fonts, and overanimated mascots that make the interface noisy or patronizing."}
- {"name":"Component catalog thinking","explanation":"Do not arrange controls as a specimen sheet. The language must live inside a real story-planning or reading scene."}
- {"name":"Soft low-contrast pastels","explanation":"Do not use pale backgrounds or washed-out type. Children need clarity, strong figure-ground contrast, and obvious states."}
- {"name":"Generic edtech templates","explanation":"Avoid card grids that could belong to any SaaS product after a palette swap; the page mechanics must shape the layout."}

### Visual Character

- Open-spread composition: the main workspace is split by a visible center gutter and mirrored paper panels, with content aligned like left and right picture-book pages.
- Full-bleed reveal panel beside smaller vignette cards, using large cropped illustration blocks to create page-turn contrast and narrative emphasis.
- Ink-frame containers: every major surface uses a 2px black border with a subtle offset warm shadow, making panels feel printed and tactile.
- Caption-ribbon typography: short labels sit in rounded pill ribbons that overlap image corners like picture-book captions and reading prompts.
- Emotion-coded page tabs: a single golden accent appears on tabs, progress marks, and current actions to signal the next story beat without rainbow clutter.

## Tokens

### Colors

| Name | Value |
|------|-------|
| primary | `#000000` |
| secondary | `#7A3E1D` |
| accent | `#F5B82E` |
| background | `#FFFFFF` |
| surface | `#FFFFFF` |
| text | `#000000` |
| muted | `#5F5A52` |
| border | `#000000` |
| error | `#B3261E` |
| success | `#1F7A3A` |
| warning | `#B26B00` |
| info | `#2457A6` |
| paper_warm | `#FFF6E2` |
| ink_soft | `#24211E` |
| sky_page | `#D9EBFF` |
| leaf_page | `#DDEECF` |
| coral_page | `#FFDDD2` |

### Typography

- **Heading Font**: Fraunces
- **Body Font**: IBM Plex Sans
- **Mono Font**: IBM Plex Mono
- **Base Size**: 16px
- **Scale Ratio**: 1.25
- **Line Height**: 1.5
- **Letter Spacing**: -0.02em
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600;9..144,700&family=IBM+Plex+Mono:wght@500;600&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap
- **Sizes**: {"caption":"12px","body":"16px","lead":"20px","h3":"25px","h2":"32px","h1":"48px"}
- **Weights**: {"regular":400,"medium":500,"semibold":600,"bold":700}

### Spacing

- **Base**: 8px
- **Scale**: ["4px","8px","12px","16px","24px","32px","48px","64px","96px"]

### Radii

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

### Shadows

- **Sm**: 3px 3px 0 #000000
- **Md**: 6px 6px 0 rgba(0,0,0,0.92)
- **Lg**: 10px 10px 0 rgba(0,0,0,0.86)

### Surfaces

- **Treatment**: paper
- **Card Style**: white printed-paper panels with black ink borders, light paper grain, and controlled warm accent washes
- **Bg Pattern**: noise

### Borders

- **Default Width**: 2px
- **Accent Width**: 4px
- **Style**: solid
- **Character**: crisp black ink outlines that define every story page, card, and control with friendly publication clarity

### Motion

- **Duration**: 180ms
- **Easing**: cubic-bezier(0.2, 0.8, 0.2, 1)
- **Philosophy**: snappy page-turn motion: small lifts and slides suggest paper handling without distracting animation

## Rules

### Composition

Use a spread-first composition with a dominant two-page stage, a visible gutter, and an intentional alternation between full-bleed story art and small supporting vignettes. Keep primary controls in the lower or side margin like reading aids, not floating SaaS chrome. Reserve the golden accent for current page, next action, and emotional emphasis. Build narrative direction left-to-right with arrows, tabs, or page numbers. Use white as the main background so warm color blocks read as illustrations rather than UI wallpaper. Keep each cluster visually complete enough that a child can infer what to do from proximity and scale.

### Hierarchy

Fraunces headlines create story-title hierarchy; IBM Plex Sans handles readable instructions; IBM Plex Mono is limited to page numbers, spread codes, and tiny production labels. The largest illustration or panel always marks the current emotional beat. Captions are short and ribboned. Controls are high-contrast, 44px or taller, and grouped by story task rather than component type.

### Density

Moderate density with generous page margins and compact captions. The interface should feel like a working picture-book spread: enough tools to plan the story, but never so many equal cards that the narrative sequence disappears.

### Signature Patterns

- A CSS center-gutter pseudo-element divides the main stage into left and right pages, including small binding dots to make the spread structure visible.
- Cards and buttons use 2px black borders plus translate-on-hover with offset box-shadow, creating a printed cutout lift instead of soft SaaS depth.
- Caption ribbons are absolutely positioned pill labels that overlap image panels and use IBM Plex Mono uppercase page language.
- Full-bleed illustration panels use simple CSS shape scenery with high value contrast, while smaller vignette cards use the same border system at reduced scale.
- Page-turn tabs use one golden accent fill and triangular folded-corner pseudo-elements to mark current and upcoming emotional beats.

## Layout

### Density

Moderate child-centered density: large reading targets, strong contrast, and enough whitespace for adults and children to point, scan, and discuss the story sequence together.

### Grid

Desktop uses a 12-column max-width 1280px stage with a 32px gutter; the central spread spans 8 columns and the planning rail spans 4. Inside the spread, a two-column page grid is divided by a 16px center gutter. Tablet collapses to an 8-column flow with the planning rail below. Mobile becomes a single-column stack with the gutter rendered as a horizontal page seam.

### Breakpoints

- **Desktop**: 1200px and up
- **Tablet**: 768px to 1199px
- **Mobile**: 480px and below

### Whitespace

Whitespace behaves like paper margin: 24px minimum around cards, 32px around the main spread, and 48px around hero areas on desktop. Never fill every corner; leave breathing room where page turns need anticipation.

### Responsive

At 1024px reduce the outer grid to one main column plus compact rail. At 768px stack the spread and rail. At 480px convert the two-page spread into sequential full-width panels and make all controls full-width.

## Guidance

### Do

- Design screens as narrative spreads with a clear current beat, next beat, and supporting vignettes.
- Use pure white backgrounds, black ink text, and the golden accent sparingly for page-turn emphasis.
- Keep letter-spacing at -0.02em across headings, body, labels, and controls.
- Give every important surface a visible 2px black border and consistent 16px or 24px radius.
- Place captions so they overlap images or panels, reinforcing image-text interplay.
- Use full-bleed illustration areas for emotional reveals and smaller vignette cards for setup details.
- Make controls at least 44px high with obvious hover, focus, disabled, and selected states.
- Shift warm supporting colors by scene emotion, but keep one accent color as the UI signal.

### Don't

- Do not use pastel page backgrounds, rainbow accents, gradient text, or crypto-style gradient buttons.
- Do not build a component catalog with sections named controls, data, or feedback.
- Do not use Poppins, Montserrat, DM Sans, Space Grotesk, or novelty cartoon fonts.
- Do not mix random border radii; stay within 0px, 16px, 24px, and 9999px.
- Do not let decorative illustration reduce contrast or obscure text.
- Do not make all cards the same size; picture-book pacing needs contrast between reveal and vignette.
- Do not rely on animation to explain structure; the page sequence must be clear when static.

### Usage Context

Best for reading companions, storyboarding tools, children’s museum interactives, literacy dashboards, author-illustrator collaboration spaces, and publishing previews where sequential art and child comprehension matter.

### Accessibility

Maintain WCAG contrast with black text on white or warm light panels; never place small text over busy art. Use 44px touch targets, visible focus rings, semantic headings, reduced-motion-friendly transitions, and captions that restate essential visual meaning.
DESIGN.md
---
version: "alpha"
name: "Storybook Page Turn"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  primary: "#000000"
  secondary: "#7A3E1D"
  accent: "#F5B82E"
  background: "#FFFFFF"
  surface: "#FFFFFF"
  text: "#000000"
  muted: "#5F5A52"
  border: "#000000"
  error: "#B3261E"
  success: "#1F7A3A"
  warning: "#B26B00"
  info: "#2457A6"
  paper_warm: "#FFF6E2"
  ink_soft: "#24211E"
  sky_page: "#D9EBFF"
  leaf_page: "#DDEECF"
  coral_page: "#FFDDD2"
typography:
  headline-lg:
    fontFamily: "Fraunces"
    fontSize: "1.953rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  headline-md:
    fontFamily: "Fraunces"
    fontSize: "1.563rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: "IBM Plex Sans"
    fontSize: "16px"
    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: "16px"
  lg: "24px"
  full: "9999px"
spacing:
  base: "8px"
  xs: "4px"
  sm: "8px"
  md: "12px"
  lg: "16px"
  xl: "24px"
  2xl: "32px"
  3xl: "48px"
  4xl: "64px"
  step-8: "96px"
components:
  color-reference-primary:
    backgroundColor: "{colors.primary}"
  color-reference-secondary:
    backgroundColor: "{colors.secondary}"
  color-reference-accent:
    backgroundColor: "{colors.accent}"
  color-reference-background:
    backgroundColor: "{colors.background}"
  color-reference-surface:
    backgroundColor: "{colors.surface}"
  color-reference-text:
    backgroundColor: "{colors.text}"
  color-reference-muted:
    backgroundColor: "{colors.muted}"
  color-reference-border:
    backgroundColor: "{colors.border}"
  color-reference-error:
    backgroundColor: "{colors.error}"
  color-reference-success:
    backgroundColor: "{colors.success}"
  color-reference-warning:
    backgroundColor: "{colors.warning}"
  color-reference-info:
    backgroundColor: "{colors.info}"
  color-reference-paper_warm:
    backgroundColor: "{colors.paper_warm}"
  color-reference-ink_soft:
    backgroundColor: "{colors.ink_soft}"
  color-reference-sky_page:
    backgroundColor: "{colors.sky_page}"
  color-reference-leaf_page:
    backgroundColor: "{colors.leaf_page}"
  color-reference-coral_page:
    backgroundColor: "{colors.coral_page}"
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
    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"
---

# Storybook Page Turn

## Overview

Storybook Page Turn is a child-centered interface language for sequential visual storytelling: it treats screens like picture-book spreads where composition, cropped illustration panels, and the emotional beat of the next page carry as much meaning as the words. It borrows from picture-book mechanics rather than decorative nostalgia: page turns create anticipation, image and text clarify each other, full-bleed moments contrast with quiet vignettes, and palette shifts mark changes in feeling. The result is warm, legible, museum-aware, and designed for children and caregivers to understand at a glance without flattening the artwork into a generic kid app.

### Values

- {"name":"Sequential pacing","explanation":"Every screen should imply before and after. Panels, page tabs, progress markers, and cropped scenes create the feeling of a spread in motion rather than an isolated dashboard."}
- {"name":"Image-text partnership","explanation":"Text blocks are short, caption-like, and positioned as companions to images. Illustrations do narrative work; copy points, labels, and confirms rather than overexplaining."}
- {"name":"Warm clarity","explanation":"The palette is warm and inviting but not pastel or low contrast. White paper fields, black ink text, and one sunny accent keep accessibility and focus intact."}
- {"name":"Page-turn emotion","explanation":"Color temperature and surface scale shift between calm planning areas and high-energy reveal areas, echoing how picture books use page turns to change mood."}
- {"name":"Child-scale affordances","explanation":"Controls are large, plain-spoken, and tactile. Roundness is consistent, borders are visible, and actions are understandable from shape and placement."}
- {"name":"Craft without clutter","explanation":"Paper grain, ink rules, and sticker-like cutouts appear as disciplined structural devices, never as a scrapbook of random decorations."}

### Anti-Values

- {"name":"Cartoon chaos","explanation":"Avoid rainbow palettes, novelty fonts, and overanimated mascots that make the interface noisy or patronizing."}
- {"name":"Component catalog thinking","explanation":"Do not arrange controls as a specimen sheet. The language must live inside a real story-planning or reading scene."}
- {"name":"Soft low-contrast pastels","explanation":"Do not use pale backgrounds or washed-out type. Children need clarity, strong figure-ground contrast, and obvious states."}
- {"name":"Generic edtech templates","explanation":"Avoid card grids that could belong to any SaaS product after a palette swap; the page mechanics must shape the layout."}

### Visual Character

- Open-spread composition: the main workspace is split by a visible center gutter and mirrored paper panels, with content aligned like left and right picture-book pages.
- Full-bleed reveal panel beside smaller vignette cards, using large cropped illustration blocks to create page-turn contrast and narrative emphasis.
- Ink-frame containers: every major surface uses a 2px black border with a subtle offset warm shadow, making panels feel printed and tactile.
- Caption-ribbon typography: short labels sit in rounded pill ribbons that overlap image corners like picture-book captions and reading prompts.
- Emotion-coded page tabs: a single golden accent appears on tabs, progress marks, and current actions to signal the next story beat without rainbow clutter.

## Colors

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

| Token | Value |
|-------|-------|
| primary | `#000000` |
| secondary | `#7A3E1D` |
| accent | `#F5B82E` |
| background | `#FFFFFF` |
| surface | `#FFFFFF` |
| text | `#000000` |
| muted | `#5F5A52` |
| border | `#000000` |
| error | `#B3261E` |
| success | `#1F7A3A` |
| warning | `#B26B00` |
| info | `#2457A6` |
| paper_warm | `#FFF6E2` |
| ink_soft | `#24211E` |
| sky_page | `#D9EBFF` |
| leaf_page | `#DDEECF` |
| coral_page | `#FFDDD2` |

## Typography

- **Headline-Lg**: Fraunces, 1.953rem, weight 700, line-height 1.1.
- **Headline-Md**: Fraunces, 1.563rem, weight 600, line-height 1.15.
- **Body-Md**: IBM Plex Sans, 16px, weight 400, line-height 1.5.
- **Label-Md**: IBM Plex Mono, 0.75rem, weight 600, line-height 1.

## Layout

### Spacing Tokens

- **Base**: `8px`
- **Xs**: `4px`
- **Sm**: `8px`
- **Md**: `12px`
- **Lg**: `16px`
- **Xl**: `24px`
- **2xl**: `32px`
- **3xl**: `48px`
- **4xl**: `64px`
- **Step-8**: `96px`

### Density

Moderate child-centered density: large reading targets, strong contrast, and enough whitespace for adults and children to point, scan, and discuss the story sequence together.

### Grid

Desktop uses a 12-column max-width 1280px stage with a 32px gutter; the central spread spans 8 columns and the planning rail spans 4. Inside the spread, a two-column page grid is divided by a 16px center gutter. Tablet collapses to an 8-column flow with the planning rail below. Mobile becomes a single-column stack with the gutter rendered as a horizontal page seam.

### Breakpoints

- **Desktop**: 1200px and up
- **Tablet**: 768px to 1199px
- **Mobile**: 480px and below

### Whitespace

Whitespace behaves like paper margin: 24px minimum around cards, 32px around the main spread, and 48px around hero areas on desktop. Never fill every corner; leave breathing room where page turns need anticipation.

### Responsive

At 1024px reduce the outer grid to one main column plus compact rail. At 768px stack the spread and rail. At 480px convert the two-page spread into sequential full-width panels and make all controls full-width.

## Elevation & Depth

### Shadows

- **Sm**: 3px 3px 0 #000000
- **Md**: 6px 6px 0 rgba(0,0,0,0.92)
- **Lg**: 10px 10px 0 rgba(0,0,0,0.86)

## Shapes

### Rounded

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

### Surfaces

- **Treatment**: paper
- **Card Style**: white printed-paper panels with black ink borders, light paper grain, and controlled warm accent washes
- **Bg Pattern**: noise

### Borders

- **Default Width**: 2px
- **Accent Width**: 4px
- **Style**: solid
- **Character**: crisp black ink outlines that define every story page, card, and control with friendly publication clarity

## Components

### Composition

Use a spread-first composition with a dominant two-page stage, a visible gutter, and an intentional alternation between full-bleed story art and small supporting vignettes. Keep primary controls in the lower or side margin like reading aids, not floating SaaS chrome. Reserve the golden accent for current page, next action, and emotional emphasis. Build narrative direction left-to-right with arrows, tabs, or page numbers. Use white as the main background so warm color blocks read as illustrations rather than UI wallpaper. Keep each cluster visually complete enough that a child can infer what to do from proximity and scale.

### Hierarchy

Fraunces headlines create story-title hierarchy; IBM Plex Sans handles readable instructions; IBM Plex Mono is limited to page numbers, spread codes, and tiny production labels. The largest illustration or panel always marks the current emotional beat. Captions are short and ribboned. Controls are high-contrast, 44px or taller, and grouped by story task rather than component type.

### Density

Moderate density with generous page margins and compact captions. The interface should feel like a working picture-book spread: enough tools to plan the story, but never so many equal cards that the narrative sequence disappears.

### Signature Patterns

- A CSS center-gutter pseudo-element divides the main stage into left and right pages, including small binding dots to make the spread structure visible.
- Cards and buttons use 2px black borders plus translate-on-hover with offset box-shadow, creating a printed cutout lift instead of soft SaaS depth.
- Caption ribbons are absolutely positioned pill labels that overlap image panels and use IBM Plex Mono uppercase page language.
- Full-bleed illustration panels use simple CSS shape scenery with high value contrast, while smaller vignette cards use the same border system at reduced scale.
- Page-turn tabs use one golden accent fill and triangular folded-corner pseudo-elements to mark current and upcoming emotional beats.

## 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/storybook-page-turn/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 Design screens as narrative spreads with a clear current beat, next beat, and supporting vignettes.
- Do Use pure white backgrounds, black ink text, and the golden accent sparingly for page-turn emphasis.
- Do Keep letter-spacing at -0.02em across headings, body, labels, and controls.
- Do Give every important surface a visible 2px black border and consistent 16px or 24px radius.
- Do Place captions so they overlap images or panels, reinforcing image-text interplay.
- Do Use full-bleed illustration areas for emotional reveals and smaller vignette cards for setup details.
- Do Make controls at least 44px high with obvious hover, focus, disabled, and selected states.
- Do Shift warm supporting colors by scene emotion, but keep one accent color as the UI signal.
- Don't Do not use pastel page backgrounds, rainbow accents, gradient text, or crypto-style gradient buttons.
- Don't Do not build a component catalog with sections named controls, data, or feedback.
- Don't Do not use Poppins, Montserrat, DM Sans, Space Grotesk, or novelty cartoon fonts.
- Don't Do not mix random border radii; stay within 0px, 16px, 24px, and 9999px.
- Don't Do not let decorative illustration reduce contrast or obscure text.
- Don't Do not make all cards the same size; picture-book pacing needs contrast between reveal and vignette.
- Don't Do not rely on animation to explain structure; the page sequence must be clear when static.

### Usage Context

Best for reading companions, storyboarding tools, children’s museum interactives, literacy dashboards, author-illustrator collaboration spaces, and publishing previews where sequential art and child comprehension matter.

### Accessibility

Maintain WCAG contrast with black text on white or warm light panels; never place small text over busy art. Use 44px touch targets, visible focus rings, semantic headings, reduced-motion-friendly transitions, and captions that restate essential visual meaning.
shadcn/ui theme
```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "storybook-page-turn",
  "type": "registry:theme",
  "title": "Storybook Page Turn shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#FFFFFF",
      "foreground": "#000000",
      "card": "#FFFFFF",
      "card-foreground": "#000000",
      "popover": "#FFFFFF",
      "popover-foreground": "#000000",
      "primary": "#000000",
      "primary-foreground": "#ffffff",
      "secondary": "#7A3E1D",
      "secondary-foreground": "#ffffff",
      "muted": "#5F5A52",
      "muted-foreground": "#000000",
      "accent": "#F5B82E",
      "accent-foreground": "#ffffff",
      "destructive": "#B3261E",
      "border": "#000000",
      "input": "#000000",
      "ring": "#F5B82E",
      "chart-1": "#000000",
      "chart-2": "#7A3E1D",
      "chart-3": "#F5B82E",
      "chart-4": "#1F7A3A",
      "chart-5": "#B26B00",
      "sidebar": "#FFFFFF",
      "sidebar-foreground": "#000000",
      "sidebar-primary": "#000000",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#2457A6",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#000000",
      "sidebar-ring": "#F5B82E",
      "radius": "16px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#000000",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#F5B82E",
      "accent-foreground": "#ffffff",
      "destructive": "#B3261E",
      "border": "#303642",
      "input": "#303642",
      "ring": "#F5B82E",
      "chart-1": "#000000",
      "chart-2": "#7A3E1D",
      "chart-3": "#F5B82E",
      "chart-4": "#1F7A3A",
      "chart-5": "#B26B00",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#000000",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#F5B82E",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#F5B82E",
      "radius": "16px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "storybook-page-turn",
    "slug": "storybook-page-turn",
    "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",
        "background",
        "border",
        "coral_page",
        "error",
        "info",
        "ink_soft",
        "leaf_page",
        "muted",
        "paper_warm",
        "primary",
        "secondary",
        "sky_page",
        "success",
        "surface",
        "text",
        "warning"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "letter_spacing",
        "line_height",
        "mono_font",
        "scale_ratio",
        "sizes",
        "weights"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm"
      ],
      "shadows": [
        "lg",
        "md",
        "sm"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "borders": [
        "accent_width",
        "character",
        "default_width",
        "style"
      ],
      "motion": [
        "duration",
        "easing",
        "philosophy"
      ]
    }
  }
}
```
in the wild

embodiments

the full element showcase
embodiment · storybook-page-turn
DESIGN.md

at a glance

Palette

Typography

headline-lgFraunces · 31px · 700

The quick brown fox jumps

headline-mdFraunces · 25px · 600

The quick brown fox jumps

body-mdIBM Plex Sans · 16px · 400

The quick brown fox jumps

label-mdIBM Plex Mono · 12px · 600

The quick brown fox jumps

Components

New
Card title

Components rendered with this language’s tokens — colors, type, and rounded corners as specified.

Spacing

  • base8px
  • xs4px
  • sm8px
  • md12px
  • lg16px
  • xl24px
  • 2xl32px
  • 3xl48px
  • 4xl64px
  • step-896px

Shape

none0px
sm16px
md16px
lg24px
full9999px
shadcn/ui

implementation kit

needs agent-authored kitcompatibility fallback
shadcn compatibility only
The generated theme variables are available, but the polished shadcn component recipes and shots have not been authored by the Katagami agent yet.
fallbackprimitives render
Compatibility proof
Local shadcn-style primitives accept the generated theme variables.
primaryaccentsurfacemutedwarningerror
table rhythm
buttonok
cardok
inputok
recommendedcompatibility fallback

DESIGN.md with shadcn

Copy this when the target app uses shadcn/ui. It packages the Katagami DESIGN.md context with the install list, theme variables, component recipes, preview-shot contract, and starter TSX in one Markdown companion.

advanced implementation filesoptional machine-readable theme, CSS, TSX starter, recipes, and preview contract
shadcn add
npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table
theme css
:root {
  --background: #FFFFFF;
  --foreground: #000000;
  --card: #FFFFFF;
  --card-foreground: #000000;
  --popover: #FFFFFF;
  --popover-foreground: #000000;
  --primary: #000000;
  --primary-foreground: #ffffff;
  --secondary: #7A3E1D;
  --secondary-foreground: #ffffff;
  --muted: #5F5A52;
  --muted-foreground: #000000;
  --accent: #F5B82E;
  --accent-foreground: #ffffff;
  --destructive: #B3261E;
  --border: #000000;
  --input: #000000;
  --ring: #F5B82E;
  --chart-1: #000000;
  --chart-2: #7A3E1D;
  --chart-3: #F5B82E;
  --chart-4: #1F7A3A;
  --chart-5: #B26B00;
  --sidebar: #FFFFFF;
  --sidebar-foreground: #000000;
  --sidebar-primary: #000000;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #2457A6;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #000000;
  --sidebar-ring: #F5B82E;
  --radius: 16px;
}

.dark {
  --background: #0f1115;
  --foreground: #f8fafc;
  --card: #181b22;
  --card-foreground: #f8fafc;
  --popover: #181b22;
  --popover-foreground: #f8fafc;
  --primary: #000000;
  --primary-foreground: #ffffff;
  --secondary: #252a33;
  --secondary-foreground: #f8fafc;
  --muted: #252a33;
  --muted-foreground: #a1a1aa;
  --accent: #F5B82E;
  --accent-foreground: #ffffff;
  --destructive: #B3261E;
  --border: #303642;
  --input: #303642;
  --ring: #F5B82E;
  --chart-1: #000000;
  --chart-2: #7A3E1D;
  --chart-3: #F5B82E;
  --chart-4: #1F7A3A;
  --chart-5: #B26B00;
  --sidebar: #181b22;
  --sidebar-foreground: #f8fafc;
  --sidebar-primary: #000000;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #F5B82E;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #303642;
  --sidebar-ring: #F5B82E;
  --radius: 16px;
}
tsx starter
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { Input } from "@/components/ui/input";
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";

export function StorybookPageTurnShadcnKit() {
  return (
    <section className="grid gap-4 rounded-[var(--radius)] border bg-background p-4 text-foreground">
      <div className="flex items-start justify-between gap-4">
        <div>
          <Badge variant="outline">shadcn/ui</Badge>
          <h2 className="mt-3 text-2xl font-semibold tracking-tight">Storybook Page Turn</h2>
          <p className="mt-1 max-w-xl text-sm text-muted-foreground">
            Use the Katagami registry theme, then compose these shadcn primitives
            with the language-specific component recipes.
          </p>
        </div>
        <Button>Apply theme</Button>
      </div>

      <Tabs defaultValue="components">
        <TabsList>
          <TabsTrigger value="components">Components</TabsTrigger>
          <TabsTrigger value="states">States</TabsTrigger>
          <TabsTrigger value="export">Export</TabsTrigger>
        </TabsList>
      </Tabs>

      <Card>
        <CardHeader>
          <CardTitle>Component recipe</CardTitle>
          <CardDescription>
            Replace this starter content with the agent-authored product scene
            from components.md and preview-shots.json.
          </CardDescription>
        </CardHeader>
        <CardContent className="grid gap-3 sm:grid-cols-[1fr_auto]">
          <Input defaultValue="Tokenized shadcn surface" aria-label="Recipe name" />
          <Button variant="secondary">Preview state</Button>
        </CardContent>
        <CardFooter className="justify-between">
          <Badge>Ready</Badge>
          <Button variant="outline">Copy recipe</Button>
        </CardFooter>
      </Card>
    </section>
  );
}
theme JSONcompatibility fallback
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "storybook-page-turn",
  "type": "registry:theme",
  "title": "Storybook Page Turn shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#FFFFFF",
      "foreground": "#000000",
      "card": "#FFFFFF",
      "card-foreground": "#000000",
      "popover": "#FFFFFF",
      "popover-foreground": "#000000",
      "primary": "#000000",
      "primary-foreground": "#ffffff",
      "secondary": "#7A3E1D",
      "secondary-foreground": "#ffffff",
      "muted": "#5F5A52",
      "muted-foreground": "#000000",
      "accent": "#F5B82E",
      "accent-foreground": "#ffffff",
      "destructive": "#B3261E",
      "border": "#000000",
      "input": "#000000",
      "ring": "#F5B82E",
      "chart-1": "#000000",
      "chart-2": "#7A3E1D",
      "chart-3": "#F5B82E",
      "chart-4": "#1F7A3A",
      "chart-5": "#B26B00",
      "sidebar": "#FFFFFF",
      "sidebar-foreground": "#000000",
      "sidebar-primary": "#000000",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#2457A6",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#000000",
      "sidebar-ring": "#F5B82E",
      "radius": "16px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#000000",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#F5B82E",
      "accent-foreground": "#ffffff",
      "destructive": "#B3261E",
      "border": "#303642",
      "input": "#303642",
      "ring": "#F5B82E",
      "chart-1": "#000000",
      "chart-2": "#7A3E1D",
      "chart-3": "#F5B82E",
      "chart-4": "#1F7A3A",
      "chart-5": "#B26B00",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#000000",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#F5B82E",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#F5B82E",
      "radius": "16px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "storybook-page-turn",
    "slug": "storybook-page-turn",
    "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",
        "background",
        "border",
        "coral_page",
        "error",
        "info",
        "ink_soft",
        "leaf_page",
        "muted",
        "paper_warm",
        "primary",
        "secondary",
        "sky_page",
        "success",
        "surface",
        "text",
        "warning"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "letter_spacing",
        "line_height",
        "mono_font",
        "scale_ratio",
        "sizes",
        "weights"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm"
      ],
      "shadows": [
        "lg",
        "md",
        "sm"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "borders": [
        "accent_width",
        "character",
        "default_width",
        "style"
      ],
      "motion": [
        "duration",
        "easing",
        "philosophy"
      ]
    }
  }
}
component recipescompatibility fallback
# Storybook Page Turn shadcn/ui Components

Artifact: `component-recipes-v1`
Author: `katagami-ui-projection`
Language ID: `storybook-page-turn`
Slug: `storybook-page-turn`

## Intent

Storybook Page Turn is a child-centered interface language for sequential visual storytelling: it treats screens like picture-book spreads where composition, cropped illustration panels, and the emotional beat of the next page carry as much meaning as the words. It borrows from picture-book mechanics rather than decorative nostalgia: page turns create anticipation, image and text clarify each other, full-bleed moments contrast with quiet vignettes, and palette shifts mark changes in feeling. The result is warm, legible, museum-aware, and designed for children and caregivers to understand at a glance without flattening the artwork into a generic kid app.

## Required primitives

- button
- card
- input
- textarea
- select
- dialog
- sheet
- tabs
- badge
- separator
- checkbox
- switch
- slider
- tooltip
- dropdown-menu
- table

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

## Token cues

Colors:

{
  "primary": "#000000",
  "secondary": "#7A3E1D",
  "accent": "#F5B82E",
  "background": "#FFFFFF",
  "surface": "#FFFFFF",
  "text": "#000000",
  "muted": "#5F5A52",
  "border": "#000000",
  "error": "#B3261E",
  "success": "#1F7A3A",
  "warning": "#B26B00",
  "info": "#2457A6",
  "paper_warm": "#FFF6E2",
  "ink_soft": "#24211E",
  "sky_page": "#D9EBFF",
  "leaf_page": "#DDEECF",
  "coral_page": "#FFDDD2"
}

Typography:

{
  "heading_font": "Fraunces",
  "body_font": "IBM Plex Sans",
  "mono_font": "IBM Plex Mono",
  "base_size": "16px",
  "scale_ratio": 1.25,
  "line_height": 1.5,
  "letter_spacing": "-0.02em",
  "google_fonts_url": "https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600;9..144,700&family=IBM+Plex+Mono:wght@500;600&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap",
  "sizes": {
    "caption": "12px",
    "body": "16px",
    "lead": "20px",
    "h3": "25px",
    "h2": "32px",
    "h1": "48px"
  },
  "weights": {
    "regular": 400,
    "medium": 500,
    "semibold": 600,
    "bold": 700
  }
}

## Visual character to preserve

- Open-spread composition: the main workspace is split by a visible center gutter and mirrored paper panels, with content aligned like left and right picture-book pages.
- Full-bleed reveal panel beside smaller vignette cards, using large cropped illustration blocks to create page-turn contrast and narrative emphasis.
- Ink-frame containers: every major surface uses a 2px black border with a subtle offset warm shadow, making panels feel printed and tactile.
- Caption-ribbon typography: short labels sit in rounded pill ribbons that overlap image corners like picture-book captions and reading prompts.
- Emotion-coded page tabs: a single golden accent appears on tabs, progress marks, and current actions to signal the next story beat without rainbow clutter.

## ShadSync visual profile

{
  "family": "paper-collage",
  "material": "paper",
  "contour": "pebble",
  "border": "solid",
  "underlay": true,
  "grain": true,
  "stickerBadges": true,
  "motion": "lift",
  "density": "balanced",
  "accents": [
    "primary",
    "accent",
    "secondary",
    "muted"
  ]
}

## Signature component recipes

### Button
Use `Button` for primary, secondary, outline, and ghost actions. Primary actions must expose the language's strongest contrast pair, while secondary and ghost actions should preserve the surface treatment instead of falling back to default neutral SaaS styling.

### Card
Use `Card`, `CardHeader`, `CardContent`, `CardFooter`, and `CardAction` as the main composition frame. Cards should demonstrate the language's surface, border, hierarchy, and density rules rather than appearing as generic rounded rectangles.

### Input and Textarea
Use `Input` and `Textarea` with visible focus rings, field labels, validation states, and the language's rhythm. Forms should show real product content, not placeholder-only controls.

### Select, Tabs, and Table
Use `Select`, `Tabs`, and `Table` to prove navigation, filtering, and dense data states. The table should show row rhythm, separators, hover/focus states, and an empty or status state when the language calls for it.

### Dialog and Sheet
Use `Dialog` for centered decisions and `Sheet` for contextual editing. Both should inherit the language's spacing, border, overlay, and motion rules.

## Preview shots

- `application-shell`: dashboard or workspace shell with navigation, cards, forms, and state badges.
- `detail-editor`: focused editing flow using input, textarea, select, switch/checkbox, dialog or sheet, and action buttons.
- `data-operations`: table-heavy operational view with tabs, dropdown menu affordances, badges, and destructive/empty states.
- Each preview shot must include a renderable `scene` payload with concrete headline, description, actions, and rows/fields/stats for the UI preview.

## Implementation contract

- Start from local `ui/src/components/ui` shadcn-style primitives; do not create a second component system.
- Apply `/katagami/shadcn/storybook-page-turn/registry-theme.json` variables, then use these recipes for composition and state design.
- Preserve Katagami token names as source metadata; shadcn semantic names are only the export surface.
- Do: Design screens as narrative spreads with a clear current beat, next beat, and supporting vignettes.; Use pure white backgrounds, black ink text, and the golden accent sparingly for page-turn emphasis.; Keep letter-spacing at -0.02em across headings, body, labels, and controls.; Give every important surface a visible 2px black border and consistent 16px or 24px radius.; Place captions so they overlap images or panels, reinforcing image-text interplay.; Use full-bleed illustration areas for emotional reveals and smaller vignette cards for setup details.; Make controls at least 44px high with obvious hover, focus, disabled, and selected states.; Shift warm supporting colors by scene emotion, but keep one accent color as the UI signal.
- Do not: Do not use pastel page backgrounds, rainbow accents, gradient text, or crypto-style gradient buttons.; Do not build a component catalog with sections named controls, data, or feedback.; Do not use Poppins, Montserrat, DM Sans, Space Grotesk, or novelty cartoon fonts.; Do not mix random border radii; stay within 0px, 16px, 24px, and 9999px.; Do not let decorative illustration reduce contrast or obscure text.; Do not make all cards the same size; picture-book pacing needs contrast between reveal and vignette.; Do not rely on animation to explain structure; the page sequence must be clear when static.

## Copy-paste component example

This generated starter proves the import shape. Production Katagami agents should replace it with a language-specific product composition.

```tsx
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { Input } from "@/components/ui/input";
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";

export function StorybookPageTurnShadcnKit() {
  return (
    <section className="grid gap-4 rounded-[var(--radius)] border bg-background p-4 text-foreground">
      <div className="flex items-start justify-between gap-4">
        <div>
          <Badge variant="outline">shadcn/ui</Badge>
          <h2 className="mt-3 text-2xl font-semibold tracking-tight">Storybook Page Turn</h2>
          <p className="mt-1 max-w-xl text-sm text-muted-foreground">
            Use the Katagami registry theme, then compose these shadcn primitives
            with the language-specific component recipes.
          </p>
        </div>
        <Button>Apply theme</Button>
      </div>

      <Tabs defaultValue="components">
        <TabsList>
          <TabsTrigger value="components">Components</TabsTrigger>
          <TabsTrigger value="states">States</TabsTrigger>
          <TabsTrigger value="export">Export</TabsTrigger>
        </TabsList>
      </Tabs>

      <Card>
        <CardHeader>
          <CardTitle>Component recipe</CardTitle>
          <CardDescription>
            Replace this starter content with the agent-authored product scene
            from components.md and preview-shots.json.
          </CardDescription>
        </CardHeader>
        <CardContent className="grid gap-3 sm:grid-cols-[1fr_auto]">
          <Input defaultValue="Tokenized shadcn surface" aria-label="Recipe name" />
          <Button variant="secondary">Preview state</Button>
        </CardContent>
        <CardFooter className="justify-between">
          <Badge>Ready</Badge>
          <Button variant="outline">Copy recipe</Button>
        </CardFooter>
      </Card>
    </section>
  );
}
```

## Layout notes

{
  "density": "Moderate child-centered density: large reading targets, strong contrast, and enough whitespace for adults and children to point, scan, and discuss the story sequence together.",
  "grid": "Desktop uses a 12-column max-width 1280px stage with a 32px gutter; the central spread spans 8 columns and the planning rail spans 4. Inside the spread, a two-column page grid is divided by a 16px center gutter. Tablet collapses to an 8-column flow with the planning rail below. Mobile becomes a single-column stack with the gutter rendered as a horizontal page seam.",
  "breakpoints": {
    "desktop": "1200px and up",
    "tablet": "768px to 1199px",
    "mobile": "480px and below"
  },
  "whitespace": "Whitespace behaves like paper margin: 24px minimum around cards, 32px around the main spread, and 48px around hero areas on desktop. Never fill every corner; leave breathing room where page turns need anticipation.",
  "responsive": "At 1024px reduce the outer grid to one main column plus compact rail. At 768px stack the spread and rail. At 480px convert the two-page spread into sequential full-width panels and make all controls full-width."
}
preview shotscompatibility fallback
{
  "artifact": "katagami:shadcn-preview-shots",
  "version": "preview-shots-v1",
  "generator": "katagami-ui-compatibility-projection",
  "generatedBy": "katagami-ui-projection",
  "requiresVisualProfile": true,
  "schema": "katagami:shadcn-preview-shots/renderable-v1",
  "renderable": true,
  "language": {
    "id": "storybook-page-turn",
    "name": "Storybook Page Turn",
    "slug": "storybook-page-turn"
  },
  "installCommand": "npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table",
  "primitives": [
    "button",
    "card",
    "input",
    "textarea",
    "select",
    "dialog",
    "sheet",
    "tabs",
    "badge",
    "separator",
    "checkbox",
    "switch",
    "slider",
    "tooltip",
    "dropdown-menu",
    "table"
  ],
  "identityNotes": [
    "Open-spread composition: the main workspace is split by a visible center gutter and mirrored paper panels, with content aligned like left and right picture-book pages.",
    "Full-bleed reveal panel beside smaller vignette cards, using large cropped illustration blocks to create page-turn contrast and narrative emphasis.",
    "Ink-frame containers: every major surface uses a 2px black border with a subtle offset warm shadow, making panels feel printed and tactile.",
    "Caption-ribbon typography: short labels sit in rounded pill ribbons that overlap image corners like picture-book captions and reading prompts.",
    "Emotion-coded page tabs: a single golden accent appears on tabs, progress marks, and current actions to signal the next story beat without rainbow clutter."
  ],
  "visualProfile": {
    "family": "paper-collage",
    "material": "paper",
    "contour": "pebble",
    "border": "solid",
    "underlay": true,
    "grain": true,
    "stickerBadges": true,
    "motion": "lift",
    "density": "balanced",
    "accents": [
      "primary",
      "accent",
      "secondary",
      "muted"
    ]
  },
  "shots": [
    {
      "id": "application-shell",
      "title": "Application shell",
      "viewport": "desktop",
      "primitives": [
        "button",
        "card",
        "input",
        "select",
        "tabs",
        "badge",
        "separator",
        "table"
      ],
      "composition": "A real product workspace with navigation, summary cards, filtering controls, and one dense content region.",
      "mustShow": [
        "primary and secondary actions",
        "card hierarchy",
        "filterable state",
        "table or list density"
      ],
      "avoid": [
        "component inventory walls",
        "placeholder-only content",
        "generic rounded SaaS chrome"
      ],
      "scene": {
        "eyebrow": "workspace spread",
        "headline": "Storybook Page Turn launch room",
        "description": "A product team workspace where navigation, filters, metrics, and dense rows carry the language's visible structure.",
        "primaryAction": "Apply theme",
        "secondaryAction": "Review states",
        "stats": [
          {
            "label": "components",
            "value": "16",
            "tone": "accent"
          },
          {
            "label": "states",
            "value": "ready"
          },
          {
            "label": "density",
            "value": "balanced",
            "tone": "warning"
          }
        ],
        "rows": [
          {
            "label": "Primary flow",
            "value": "mapped",
            "status": "active"
          },
          {
            "label": "Token coverage",
            "value": "semantic",
            "status": "synced"
          },
          {
            "label": "Responsive proof",
            "value": "queued",
            "status": "review"
          }
        ],
        "statuses": [
          "Active",
          "Synced",
          "Draft"
        ]
      }
    },
    {
      "id": "detail-editor",
      "title": "Detail editor",
      "viewport": "tablet",
      "primitives": [
        "button",
        "card",
        "input",
        "textarea",
        "select",
        "checkbox",
        "switch",
        "slider",
        "dialog",
        "sheet"
      ],
      "composition": "A focused editing flow with form fields, validation, confirmation, and a contextual side panel.",
      "mustShow": [
        "focus ring",
        "error or destructive state",
        "dialog or sheet treatment",
        "written guidance content"
      ],
      "avoid": [
        "unstyled browser controls",
        "floating cards inside cards",
        "missing labels"
      ],
      "scene": {
        "eyebrow": "editing flow",
        "headline": "Language recipe editor",
        "description": "A focused form proving labels, validation, toggles, panel rhythm, and action hierarchy.",
        "primaryAction": "Save recipe",
        "secondaryAction": "Open sheet",
        "fields": [
          {
            "label": "Component family",
            "value": "Narrative cards"
          },
          {
            "label": "State treatment",
            "value": "Visible focus + validation"
          },
          {
            "label": "Motion",
            "value": "Small lift, no opacity-only fade"
          }
        ],
        "statuses": [
          "Focus",
          "Invalid",
          "Confirmed"
        ]
      }
    },
    {
      "id": "data-operations",
      "title": "Data operations",
      "viewport": "mobile",
      "primitives": [
        "button",
        "tabs",
        "badge",
        "dropdown-menu",
        "table",
        "tooltip",
        "separator"
      ],
      "composition": "A compact operational view proving row rhythm, stacked actions, menu states, badges, and empty/destructive states.",
      "mustShow": [
        "responsive reflow",
        "dense row styling",
        "menu affordance",
        "status badge system"
      ],
      "avoid": [
        "desktop-only tables",
        "text overflow",
        "default shadcn spacing without Katagami character"
      ],
      "scene": {
        "eyebrow": "operations",
        "headline": "Compact review queue",
        "description": "A narrow viewport scene with rows, menus, tooltips, badges, and destructive affordances.",
        "primaryAction": "Resolve",
        "secondaryAction": "Filter",
        "rows": [
          {
            "label": "Button hierarchy",
            "value": "approved",
            "status": "ok"
          },
          {
            "label": "Table rhythm",
            "value": "needs pass",
            "status": "watch"
          },
          {
            "label": "Empty state",
            "value": "designed",
            "status": "done"
          }
        ],
        "statuses": [
          "Queued",
          "Blocked",
          "Done"
        ]
      }
    }
  ],
  "componentRecipes": [
    {
      "primitive": "button",
      "intent": "Prove action hierarchy, focus, disabled, and destructive states."
    },
    {
      "primitive": "card",
      "intent": "Carry the language surface, border, elevation, and density rules."
    },
    {
      "primitive": "input",
      "intent": "Show labels, focus rings, validation, and spacing rhythm."
    },
    {
      "primitive": "textarea",
      "intent": "Show longer guidance, validation copy, and writing density."
    },
    {
      "primitive": "select",
      "intent": "Show filtering, selection contrast, and menu trigger styling."
    },
    {
      "primitive": "dialog",
      "intent": "Show centered decision states and overlay treatment."
    },
    {
      "primitive": "sheet",
      "intent": "Show contextual side panels and responsive editing."
    },
    {
      "primitive": "tabs",
      "intent": "Show navigational structure and active/inactive contrast."
    },
    {
      "primitive": "badge",
      "intent": "Show compact status vocabulary and semantic colors."
    },
    {
      "primitive": "separator",
      "intent": "Show section rhythm without generic gray dividers."
    },
    {
      "primitive": "checkbox",
      "intent": "Show binary selection with visible focus and checked states."
    },
    {
      "primitive": "switch",
      "intent": "Show settings toggles and on/off contrast."
    },
    {
      "primitive": "slider",
      "intent": "Show numeric adjustment with track/thumb styling."
    },
    {
      "primitive": "tooltip",
      "intent": "Show concise explanation styling above compact controls."
    },
    {
      "primitive": "dropdown-menu",
      "intent": "Show action menus, destructive items, and grouped choices."
    },
    {
      "primitive": "table",
      "intent": "Show dense operational data, separators, row states, and responsive behavior."
    }
  ],
  "qualityRules": {
    "do": [
      "Design screens as narrative spreads with a clear current beat, next beat, and supporting vignettes.",
      "Use pure white backgrounds, black ink text, and the golden accent sparingly for page-turn emphasis.",
      "Keep letter-spacing at -0.02em across headings, body, labels, and controls.",
      "Give every important surface a visible 2px black border and consistent 16px or 24px radius.",
      "Place captions so they overlap images or panels, reinforcing image-text interplay.",
      "Use full-bleed illustration areas for emotional reveals and smaller vignette cards for setup details.",
      "Make controls at least 44px high with obvious hover, focus, disabled, and selected states.",
      "Shift warm supporting colors by scene emotion, but keep one accent color as the UI signal."
    ],
    "dont": [
      "Do not use pastel page backgrounds, rainbow accents, gradient text, or crypto-style gradient buttons.",
      "Do not build a component catalog with sections named controls, data, or feedback.",
      "Do not use Poppins, Montserrat, DM Sans, Space Grotesk, or novelty cartoon fonts.",
      "Do not mix random border radii; stay within 0px, 16px, 24px, and 9999px.",
      "Do not let decorative illustration reduce contrast or obscure text.",
      "Do not make all cards the same size; picture-book pacing needs contrast between reveal and vignette.",
      "Do not rely on animation to explain structure; the page sequence must be clear when static."
    ]
  }
}
related

More like this