Diorama

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

Published

Download DESIGN.md

Portable DESIGN.md — tokens plus the paired art style. Agents must generate real images.

the spec

specification

philosophy

summary

Diorama is a modern picture-book language for interfaces that need to feel readable, warm and sequential for young children and the adults reading with them. It treats the screen as an opened storybook spread that stands up: each scene is a little paper theatre, cut and torn from warm construction paper and stacked into depth planes that rise off the page. A friendly round-faced character cutout anchors every beat so a pre-literate child can navigate by picture before word, and moving forward feels like turning a page rather than operating software. It keeps the soul of the storybook it descends from — cream paper, read-aloud rhythm, warm high-clarity contrast, handmade texture as a comprehension aid, one primary focus per view — and reconceives the expression as the Pop-up Rise.

values

the Pop-up Rise: information stands up in small readable beats, like a spread openingrecognizable character-led wayfinding for young readerssoft high-clarity contrast that avoids both glare and mushinesshandmade cut-paper texture used as a comprehension aid rather than decorationlarge planes and generous whitespace for pre-literate scanninga read-aloud display voice that stays legible, over a fine clear bodyage-appropriate complexity with one primary focus per view

anti-values

×dense dashboards with many equal-weight controls×slick tech gradients or glassmorphism that erase the paper material×ink-outlined boxes and coloured edge rails standing in for depth×tiny icon-only interactions that require adult interpretation×overstimulating rainbow palettes without narrative hierarchy×chunky, semibold or oversized body text

visual character

Opened-spread scenes stand up from warm cream paper in stacked cut-paper depth planes, each casting a soft shadow onto the layer behind.Torn deckled edges and a faint paper-fibre grain give every shape a hand-cut quality; a light rake shifts across the grain as a scene stands.Round-faced character cutouts and simple prop silhouettes anchor navigation before any text is read.Folio page-numbers, round page-pip trails, and a peeling top-right corner carry an unmistakable page-turn rhythm.Fraunces read-aloud display over a fine Atkinson Hyperlegible body; warm poppy, meadow and marigold papers used like highlighters on cream.

tokens

colors18 items

#FAF2DF

surface

#FFFCF5

surface_solid

#F3E7CE

text

#33241A

muted

#705A3E

border

#EAD9B6

accent

#CE471E

accent_ink

#A8380F

accent_2

#2E8C6A

accent2_ink

#1C6349

accent_soft

#F2B33D

accent_3

#F2B33D

on_accent

#FFFDF8

on_accent_dark

#33241A

success

#2E7D48

warning

#E08A2B

error

#BE3A28

info

#3E97B0

typography10 items

base size: 17.5px
body font: Atkinson Hyperlegible
heading font: Fraunces
mono font: none
heading weight: 700
heading transform: none
letter spacing: -0.01em
line height: 1.55
scale ratio: 1.25
google fonts url: https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:ital,wght@0,400;0,700;1,400&family=Fraunces:opsz,wght@9..144,400..900&display=swap

radii4 items

none: 0px
md: 16px
lg: 24px
full: 9999px

shadows3 items

sm: 0 2px 6px rgba(90,60,30,0.10)
md: 0 12px 24px rgba(90,60,30,0.17)
lg: 0 26px 50px rgba(90,60,30,0.20)

spacing2 items

base: 8px
scale: 4, 8, 12, 16, 24, 32, 48, 64, 80, 104

surfaces3 items

treatment: Warm cream paper with a faint fibre grain and a soft sponged gouache wash; scenes are layers of cut paper stacked with soft cast shadows between planes.
card style: A raised cut-paper plane (cream surface, radius 16) casting a soft short drop-shadow onto the page behind it; its edge is read by the shadow and the paper's own colour, never an ink outline or coloured side-rail; it lifts a few pixels on hover (the Pop-up Rise).
bg pattern: A very faint paper-fibre speckle and one or two soft gouache blobs for organic colour, with reserved quiet zones under every line of copy.

borders4 items

default width: 1px
accent width: 2px
style: solid
character: Hairlines are soft warm-sand and used rarely, only inside form wells. Cut-paper edges are read by their cast shadow and the paper's own colour against the layer behind — never by an ink outline, a heavy border, or a coloured edge rail on any card or block.

motion3 items

duration: 260ms
easing: cubic-bezier(.2,.8,.24,1)
philosophy: Motion is a paper piece standing up: a short rise (translateY up, a touch of rotateX) that settles on a soft tail, and a page turning (a corner peel, a spread swinging open). Small, warm, hand-touched — never slippery app motion. On the landing the rise and the page-turns are scroll-scrubbed and a light rake shifts across the paper grain with the pointer. Respect prefers-reduced-motion: content is fully settled and readable with no motion and no JavaScript.

rules

composition

Compose each view as an opened picture-book spread: one large standing story-plane carrying the page thesis, a slim supporting column of choices, and a clear next-page cue. Keep one dominant character or prop cutout per section. Hold cream pauses between beats so the eye rests like a page turn. Never let more than three saturated papers compete in one region.

hierarchy

Display is Fraunces at read-aloud scale for the page thesis; body is Atkinson Hyperlegible at a fine, legible 17.5px; small labels are Atkinson caps. The largest standing scene carries the thesis, the primary action is one bold poppy button, and supporting notes sit on quiet kraft chips. Reserve poppy-red, meadow-green and marigold for story objects and priority cues.

density

Low-to-medium density chosen for child comprehension: each viewport exposes one main story beat, one supporting cluster, and one clear next action. Secondary information tucks into small paper sticker-notes rather than grids.

signature patterns

The Pop-up Rise: every panel is a cut-paper plane that rises from flat to standing on enter, its shadow shortening as it stands; on hover a control lifts a few pixels like a paper tab.Depth-plane staging: a scene is built from stacked cut-paper flats (backdrop, scenery, character, foreground) offset in parallax, each casting a soft shadow onto the plane behind for real pop-up depth.Page-turn folios: sequence reads through a folio page-number and a row of round page-pips; the current spread's top-right corner peels to preview the next — a page-turn, never an arrow.Character cutouts: a friendly round-faced child or animal cutout anchors each scene as a nonverbal wayfinding marker, always paired with text.Deckle edges and fibre: cut-paper shapes carry soft torn edges and a faint fibre grain, visible but always quiet behind copy; a light rake reveals the grain as a scene stands.

layout

density

Low-to-medium for child comprehension: one standing story-plane, one supporting cluster, one clear next action per view.

grid

Desktop uses a 12-column max-1180px opened spread with 24px gutters and a soft centre gutter recalling the book's spine; tablet collapses to a considered two-up spread; mobile is one column with the action following the scene.

breakpoints

mobile: 0-640px single page column (character, scene, choices, next-page cue)
tablet: 641-1024px its own two-up spread, never the mobile column stretched wide
desktop: 1025px+ twelve-column opened spread (max 1180px)

whitespace

Cream margins of at least 20px mobile, 40px tablet, 64px desktop; 32-64px pauses between beats so the layout breathes like page turns.

responsive

Preserve the reading beats on smaller screens (scene, choices, read-aloud note, next-page). Planes may stack but keep their cast shadow and character anchor. Oversized display shrinks with clamp() and wraps; nav wraps, never spills.

guidance

Let one cut-paper plane stand as the page thesis; give it the most rise and the shortest shadow.
Anchor every major scene with one friendly character or prop cutout, always paired with text.
Keep copy short, rhythmic and readable aloud; hold cream pauses between beats.
Reserve poppy-red, meadow-green and marigold for story objects and priority cues.
Read paper edges by their cast shadow; keep the paper's own colour doing the work.
Show sequence with a folio page-number, a row of round page-pips, and a corner peel.
Keep body at a fine 17.5px and let only the display carry read-aloud scale.

avoid

Do not outline cards with ink or put a coloured edge rail or side stripe on any block.
Do not place textured paper or busy imagery directly under long body copy.
Do not rely on icon-only controls for core actions; keep touch targets child-sized.
Do not let more than three saturated papers compete in one region.
Do not make body text chunky, semibold or big; keep the mid-tier quiet.
Do not tilt every plane; the rise and a gentle paper tilt are accents, not a default.
Do not use neon, glassmorphism or slick tech gradients that erase the paper.

imagery

pairs with

deckle

summary

Torn-and-cut construction-paper collage: layered matte opaque papers with deckled edges and a faint fibre grain, each flat shape casting a soft short shadow onto the layer behind for gentle pop-up depth. Warm cream ground, bold simple friendly shapes, flat even light. Reserve quiet cream zones for type.

palette hint

warm cream, poppy red-orange, meadow green, marigold yellow, soft teal (water only), espresso-brown ink

subjects

meadows and rolling hills, rivers and little boats, storybook forests, a rising sun, friendly child and animal cutouts, cosy villages, simple props (teapot, bicycle)

illustration style

cut-paper collage in the tradition of hand-cut picture books; simple friendly rounded shapes; texture from sponged gouache and crayon on the papers before cutting

hero image direction

ONE full-bleed cut-paper scene with a generous open cream sky reserved upper-left for the display wordmark; a low round marigold sun and small character cutouts on the nearest hill

icon style

simple line icons (1.8-2.2px stroke) or small cut-paper prop silhouettes; never emoji

katagami spec

# Diorama

## Philosophy

### Values

- the Pop-up Rise: information stands up in small readable beats, like a spread opening
- recognizable character-led wayfinding for young readers
- soft high-clarity contrast that avoids both glare and mushiness
- handmade cut-paper texture used as a comprehension aid rather than decoration
- large planes and generous whitespace for pre-literate scanning
- a read-aloud display voice that stays legible, over a fine clear body
- age-appropriate complexity with one primary focus per view

### Anti-Values

- dense dashboards with many equal-weight controls
- slick tech gradients or glassmorphism that erase the paper material
- ink-outlined boxes and coloured edge rails standing in for depth
- tiny icon-only interactions that require adult interpretation
- overstimulating rainbow palettes without narrative hierarchy
- chunky, semibold or oversized body text

### Visual Character

- Opened-spread scenes stand up from warm cream paper in stacked cut-paper depth planes, each casting a soft shadow onto the layer behind.
- Torn deckled edges and a faint paper-fibre grain give every shape a hand-cut quality; a light rake shifts across the grain as a scene stands.
- Round-faced character cutouts and simple prop silhouettes anchor navigation before any text is read.
- Folio page-numbers, round page-pip trails, and a peeling top-right corner carry an unmistakable page-turn rhythm.
- Fraunces read-aloud display over a fine Atkinson Hyperlegible body; warm poppy, meadow and marigold papers used like highlighters on cream.

## Tokens

### Colors

| Name | Value |
|------|-------|
| bg | `#FAF2DF` |
| surface | `#FFFCF5` |
| surface_solid | `#F3E7CE` |
| text | `#33241A` |
| muted | `#705A3E` |
| border | `#EAD9B6` |
| accent | `#CE471E` |
| accent_ink | `#A8380F` |
| accent_2 | `#2E8C6A` |
| accent2_ink | `#1C6349` |
| accent_soft | `#F2B33D` |
| accent_3 | `#F2B33D` |
| on_accent | `#FFFDF8` |
| on_accent_dark | `#33241A` |
| success | `#2E7D48` |
| warning | `#E08A2B` |
| error | `#BE3A28` |
| info | `#3E97B0` |

### Typography

- **Base Size**: 17.5px
- **Body Font**: Atkinson Hyperlegible
- **Heading Font**: Fraunces
- **Mono Font**: none
- **Heading Weight**: 700
- **Heading Transform**: none
- **Letter Spacing**: -0.01em
- **Line Height**: 1.55
- **Scale Ratio**: 1.25
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:ital,wght@0,400;0,700;1,400&family=Fraunces:opsz,wght@9..144,400..900&display=swap

### Radii

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

### Shadows

- **Sm**: 0 2px 6px rgba(90,60,30,0.10)
- **Md**: 0 12px 24px rgba(90,60,30,0.17)
- **Lg**: 0 26px 50px rgba(90,60,30,0.20)

### Spacing

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

### Surfaces

- **Treatment**: Warm cream paper with a faint fibre grain and a soft sponged gouache wash; scenes are layers of cut paper stacked with soft cast shadows between planes.
- **Card Style**: A raised cut-paper plane (cream surface, radius 16) casting a soft short drop-shadow onto the page behind it; its edge is read by the shadow and the paper's own colour, never an ink outline or coloured side-rail; it lifts a few pixels on hover (the Pop-up Rise).
- **Bg Pattern**: A very faint paper-fibre speckle and one or two soft gouache blobs for organic colour, with reserved quiet zones under every line of copy.

### Borders

- **Default Width**: 1px
- **Accent Width**: 2px
- **Style**: solid
- **Character**: Hairlines are soft warm-sand and used rarely, only inside form wells. Cut-paper edges are read by their cast shadow and the paper's own colour against the layer behind — never by an ink outline, a heavy border, or a coloured edge rail on any card or block.

### Motion

- **Duration**: 260ms
- **Easing**: cubic-bezier(.2,.8,.24,1)
- **Philosophy**: Motion is a paper piece standing up: a short rise (translateY up, a touch of rotateX) that settles on a soft tail, and a page turning (a corner peel, a spread swinging open). Small, warm, hand-touched — never slippery app motion. On the landing the rise and the page-turns are scroll-scrubbed and a light rake shifts across the paper grain with the pointer. Respect prefers-reduced-motion: content is fully settled and readable with no motion and no JavaScript.

## Rules

### Composition

Compose each view as an opened picture-book spread: one large standing story-plane carrying the page thesis, a slim supporting column of choices, and a clear next-page cue. Keep one dominant character or prop cutout per section. Hold cream pauses between beats so the eye rests like a page turn. Never let more than three saturated papers compete in one region.

### Hierarchy

Display is Fraunces at read-aloud scale for the page thesis; body is Atkinson Hyperlegible at a fine, legible 17.5px; small labels are Atkinson caps. The largest standing scene carries the thesis, the primary action is one bold poppy button, and supporting notes sit on quiet kraft chips. Reserve poppy-red, meadow-green and marigold for story objects and priority cues.

### Density

Low-to-medium density chosen for child comprehension: each viewport exposes one main story beat, one supporting cluster, and one clear next action. Secondary information tucks into small paper sticker-notes rather than grids.

### Signature Patterns

- The Pop-up Rise: every panel is a cut-paper plane that rises from flat to standing on enter, its shadow shortening as it stands; on hover a control lifts a few pixels like a paper tab.
- Depth-plane staging: a scene is built from stacked cut-paper flats (backdrop, scenery, character, foreground) offset in parallax, each casting a soft shadow onto the plane behind for real pop-up depth.
- Page-turn folios: sequence reads through a folio page-number and a row of round page-pips; the current spread's top-right corner peels to preview the next — a page-turn, never an arrow.
- Character cutouts: a friendly round-faced child or animal cutout anchors each scene as a nonverbal wayfinding marker, always paired with text.
- Deckle edges and fibre: cut-paper shapes carry soft torn edges and a faint fibre grain, visible but always quiet behind copy; a light rake reveals the grain as a scene stands.

## Layout

### Density

Low-to-medium for child comprehension: one standing story-plane, one supporting cluster, one clear next action per view.

### Grid

Desktop uses a 12-column max-1180px opened spread with 24px gutters and a soft centre gutter recalling the book's spine; tablet collapses to a considered two-up spread; mobile is one column with the action following the scene.

### Breakpoints

- **Mobile**: 0-640px single page column (character, scene, choices, next-page cue)
- **Tablet**: 641-1024px its own two-up spread, never the mobile column stretched wide
- **Desktop**: 1025px+ twelve-column opened spread (max 1180px)

### Whitespace

Cream margins of at least 20px mobile, 40px tablet, 64px desktop; 32-64px pauses between beats so the layout breathes like page turns.

### Responsive

Preserve the reading beats on smaller screens (scene, choices, read-aloud note, next-page). Planes may stack but keep their cast shadow and character anchor. Oversized display shrinks with clamp() and wraps; nav wraps, never spills.

## Guidance

### Do

- Let one cut-paper plane stand as the page thesis; give it the most rise and the shortest shadow.
- Anchor every major scene with one friendly character or prop cutout, always paired with text.
- Keep copy short, rhythmic and readable aloud; hold cream pauses between beats.
- Reserve poppy-red, meadow-green and marigold for story objects and priority cues.
- Read paper edges by their cast shadow; keep the paper's own colour doing the work.
- Show sequence with a folio page-number, a row of round page-pips, and a corner peel.
- Keep body at a fine 17.5px and let only the display carry read-aloud scale.

### Don't

- Do not outline cards with ink or put a coloured edge rail or side stripe on any block.
- Do not place textured paper or busy imagery directly under long body copy.
- Do not rely on icon-only controls for core actions; keep touch targets child-sized.
- Do not let more than three saturated papers compete in one region.
- Do not make body text chunky, semibold or big; keep the mid-tier quiet.
- Do not tilt every plane; the rise and a gentle paper tilt are accents, not a default.
- Do not use neon, glassmorphism or slick tech gradients that erase the paper.

### Usage Context

Best for children's picture-book discovery, early-literacy tools, read-aloud companions, classroom story stations, family library apps, and playful onboarding for young audiences.

### Accessibility

Maintain WCAG AA contrast on text; keep body at 17.5px; pair every character cutout with text; accent hues appear as text only in dark ink variants (poppy #A8380F, green #1C6349), while bright hues stay on fills and swatches; avoid flashing motion and respect prefers-reduced-motion; preserve logical reading order across breakpoints.

## Imagery Direction

### Pairs With

deckle

### Summary

Torn-and-cut construction-paper collage: layered matte opaque papers with deckled edges and a faint fibre grain, each flat shape casting a soft short shadow onto the layer behind for gentle pop-up depth. Warm cream ground, bold simple friendly shapes, flat even light. Reserve quiet cream zones for type.

### Palette Hint

warm cream, poppy red-orange, meadow green, marigold yellow, soft teal (water only), espresso-brown ink

### Subjects

meadows and rolling hills, rivers and little boats, storybook forests, a rising sun, friendly child and animal cutouts, cosy villages, simple props (teapot, bicycle)

### Illustration Style

cut-paper collage in the tradition of hand-cut picture books; simple friendly rounded shapes; texture from sponged gouache and crayon on the papers before cutting

### Hero Image Direction

ONE full-bleed cut-paper scene with a generous open cream sky reserved upper-left for the display wordmark; a low round marigold sun and small character cutouts on the nearest hill

### Icon Style

simple line icons (1.8-2.2px stroke) or small cut-paper prop silhouettes; never emoji

DESIGN.md

---
version: "alpha"
name: "Diorama"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  bg: "#FAF2DF"
  surface: "#FFFCF5"
  surface_solid: "#F3E7CE"
  text: "#33241A"
  muted: "#705A3E"
  border: "#EAD9B6"
  accent: "#CE471E"
  accent_ink: "#A8380F"
  accent_2: "#2E8C6A"
  accent2_ink: "#1C6349"
  accent_soft: "#F2B33D"
  accent_3: "#F2B33D"
  on_accent: "#FFFDF8"
  on_accent_dark: "#33241A"
  success: "#2E7D48"
  warning: "#E08A2B"
  error: "#BE3A28"
  info: "#3E97B0"
typography:
  headline-lg:
    fontFamily: "Fraunces"
    fontSize: "2.136rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.01em"
  headline-md:
    fontFamily: "Fraunces"
    fontSize: "1.709rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.01em"
  body-md:
    fontFamily: "Atkinson Hyperlegible"
    fontSize: "17.5px"
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: "-0.01em"
  label-md:
    fontFamily: "none"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
rounded:
  none: "0px"
  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: "80px"
  step-9: "104px"
components:
  color-reference-bg:
    backgroundColor: "{colors.bg}"
  color-reference-surface:
    backgroundColor: "{colors.surface}"
  color-reference-surface_solid:
    backgroundColor: "{colors.surface_solid}"
  color-reference-text:
    backgroundColor: "{colors.text}"
  color-reference-muted:
    backgroundColor: "{colors.muted}"
  color-reference-border:
    backgroundColor: "{colors.border}"
  color-reference-accent:
    backgroundColor: "{colors.accent}"
  color-reference-accent_ink:
    backgroundColor: "{colors.accent_ink}"
  color-reference-accent_2:
    backgroundColor: "{colors.accent_2}"
  color-reference-accent2_ink:
    backgroundColor: "{colors.accent2_ink}"
  color-reference-accent_soft:
    backgroundColor: "{colors.accent_soft}"
  color-reference-accent_3:
    backgroundColor: "{colors.accent_3}"
  color-reference-on_accent:
    backgroundColor: "{colors.on_accent}"
  color-reference-on_accent_dark:
    backgroundColor: "{colors.on_accent_dark}"
  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: "#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"
---

# Diorama

## Overview

Diorama is a modern picture-book language for interfaces that need to feel readable, warm and sequential for young children and the adults reading with them. It treats the screen as an opened storybook spread that stands up: each scene is a little paper theatre, cut and torn from warm construction paper and stacked into depth planes that rise off the page. A friendly round-faced character cutout anchors every beat so a pre-literate child can navigate by picture before word, and moving forward feels like turning a page rather than operating software. It keeps the soul of the storybook it descends from — cream paper, read-aloud rhythm, warm high-clarity contrast, handmade texture as a comprehension aid, one primary focus per view — and reconceives the expression as the Pop-up Rise.

### Values

- the Pop-up Rise: information stands up in small readable beats, like a spread opening
- recognizable character-led wayfinding for young readers
- soft high-clarity contrast that avoids both glare and mushiness
- handmade cut-paper texture used as a comprehension aid rather than decoration
- large planes and generous whitespace for pre-literate scanning
- a read-aloud display voice that stays legible, over a fine clear body
- age-appropriate complexity with one primary focus per view

### Anti-Values

- dense dashboards with many equal-weight controls
- slick tech gradients or glassmorphism that erase the paper material
- ink-outlined boxes and coloured edge rails standing in for depth
- tiny icon-only interactions that require adult interpretation
- overstimulating rainbow palettes without narrative hierarchy
- chunky, semibold or oversized body text

### Visual Character

- Opened-spread scenes stand up from warm cream paper in stacked cut-paper depth planes, each casting a soft shadow onto the layer behind.
- Torn deckled edges and a faint paper-fibre grain give every shape a hand-cut quality; a light rake shifts across the grain as a scene stands.
- Round-faced character cutouts and simple prop silhouettes anchor navigation before any text is read.
- Folio page-numbers, round page-pip trails, and a peeling top-right corner carry an unmistakable page-turn rhythm.
- Fraunces read-aloud display over a fine Atkinson Hyperlegible body; warm poppy, meadow and marigold papers used like highlighters on cream.

## 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 | `#FAF2DF` |
| surface | `#FFFCF5` |
| surface_solid | `#F3E7CE` |
| text | `#33241A` |
| muted | `#705A3E` |
| border | `#EAD9B6` |
| accent | `#CE471E` |
| accent_ink | `#A8380F` |
| accent_2 | `#2E8C6A` |
| accent2_ink | `#1C6349` |
| accent_soft | `#F2B33D` |
| accent_3 | `#F2B33D` |
| on_accent | `#FFFDF8` |
| on_accent_dark | `#33241A` |
| success | `#2E7D48` |
| warning | `#E08A2B` |
| error | `#BE3A28` |
| info | `#3E97B0` |

## Typography

- **Headline-Lg**: Fraunces, 2.136rem, weight 700, line-height 1.1.
- **Headline-Md**: Fraunces, 1.709rem, weight 600, line-height 1.15.
- **Body-Md**: Atkinson Hyperlegible, 17.5px, weight 400, line-height 1.5.
- **Label-Md**: none, 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**: `80px`
- **Step-9**: `104px`

### Density

Low-to-medium for child comprehension: one standing story-plane, one supporting cluster, one clear next action per view.

### Grid

Desktop uses a 12-column max-1180px opened spread with 24px gutters and a soft centre gutter recalling the book's spine; tablet collapses to a considered two-up spread; mobile is one column with the action following the scene.

### Breakpoints

- **Mobile**: 0-640px single page column (character, scene, choices, next-page cue)
- **Tablet**: 641-1024px its own two-up spread, never the mobile column stretched wide
- **Desktop**: 1025px+ twelve-column opened spread (max 1180px)

### Whitespace

Cream margins of at least 20px mobile, 40px tablet, 64px desktop; 32-64px pauses between beats so the layout breathes like page turns.

### Responsive

Preserve the reading beats on smaller screens (scene, choices, read-aloud note, next-page). Planes may stack but keep their cast shadow and character anchor. Oversized display shrinks with clamp() and wraps; nav wraps, never spills.

## Elevation & Depth

### Shadows

- **Sm**: 0 2px 6px rgba(90,60,30,0.10)
- **Md**: 0 12px 24px rgba(90,60,30,0.17)
- **Lg**: 0 26px 50px rgba(90,60,30,0.20)

## Shapes

### Rounded

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

### Surfaces

- **Treatment**: Warm cream paper with a faint fibre grain and a soft sponged gouache wash; scenes are layers of cut paper stacked with soft cast shadows between planes.
- **Card Style**: A raised cut-paper plane (cream surface, radius 16) casting a soft short drop-shadow onto the page behind it; its edge is read by the shadow and the paper's own colour, never an ink outline or coloured side-rail; it lifts a few pixels on hover (the Pop-up Rise).
- **Bg Pattern**: A very faint paper-fibre speckle and one or two soft gouache blobs for organic colour, with reserved quiet zones under every line of copy.

### Borders

- **Default Width**: 1px
- **Accent Width**: 2px
- **Style**: solid
- **Character**: Hairlines are soft warm-sand and used rarely, only inside form wells. Cut-paper edges are read by their cast shadow and the paper's own colour against the layer behind — never by an ink outline, a heavy border, or a coloured edge rail on any card or block.

## Components

### Composition

Compose each view as an opened picture-book spread: one large standing story-plane carrying the page thesis, a slim supporting column of choices, and a clear next-page cue. Keep one dominant character or prop cutout per section. Hold cream pauses between beats so the eye rests like a page turn. Never let more than three saturated papers compete in one region.

### Hierarchy

Display is Fraunces at read-aloud scale for the page thesis; body is Atkinson Hyperlegible at a fine, legible 17.5px; small labels are Atkinson caps. The largest standing scene carries the thesis, the primary action is one bold poppy button, and supporting notes sit on quiet kraft chips. Reserve poppy-red, meadow-green and marigold for story objects and priority cues.

### Density

Low-to-medium density chosen for child comprehension: each viewport exposes one main story beat, one supporting cluster, and one clear next action. Secondary information tucks into small paper sticker-notes rather than grids.

### Signature Patterns

- The Pop-up Rise: every panel is a cut-paper plane that rises from flat to standing on enter, its shadow shortening as it stands; on hover a control lifts a few pixels like a paper tab.
- Depth-plane staging: a scene is built from stacked cut-paper flats (backdrop, scenery, character, foreground) offset in parallax, each casting a soft shadow onto the plane behind for real pop-up depth.
- Page-turn folios: sequence reads through a folio page-number and a row of round page-pips; the current spread's top-right corner peels to preview the next — a page-turn, never an arrow.
- Character cutouts: a friendly round-faced child or animal cutout anchors each scene as a nonverbal wayfinding marker, always paired with text.
- Deckle edges and fibre: cut-paper shapes carry soft torn edges and a faint fibre grain, visible but always quiet behind copy; a light rake reveals the grain as a scene stands.

## 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-019fe2a2-6611-7923-bc68-0549219c7d1e/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 Let one cut-paper plane stand as the page thesis; give it the most rise and the shortest shadow.
- Do Anchor every major scene with one friendly character or prop cutout, always paired with text.
- Do Keep copy short, rhythmic and readable aloud; hold cream pauses between beats.
- Do Reserve poppy-red, meadow-green and marigold for story objects and priority cues.
- Do Read paper edges by their cast shadow; keep the paper's own colour doing the work.
- Do Show sequence with a folio page-number, a row of round page-pips, and a corner peel.
- Do Keep body at a fine 17.5px and let only the display carry read-aloud scale.
- Don't Do not outline cards with ink or put a coloured edge rail or side stripe on any block.
- Don't Do not place textured paper or busy imagery directly under long body copy.
- Don't Do not rely on icon-only controls for core actions; keep touch targets child-sized.
- Don't Do not let more than three saturated papers compete in one region.
- Don't Do not make body text chunky, semibold or big; keep the mid-tier quiet.
- Don't Do not tilt every plane; the rise and a gentle paper tilt are accents, not a default.
- Don't Do not use neon, glassmorphism or slick tech gradients that erase the paper.

### Usage Context

Best for children's picture-book discovery, early-literacy tools, read-aloud companions, classroom story stations, family library apps, and playful onboarding for young audiences.

### Accessibility

Maintain WCAG AA contrast on text; keep body at 17.5px; pair every character cutout with text; accent hues appear as text only in dark ink variants (poppy #A8380F, green #1C6349), while bright hues stay on fills and swatches; avoid flashing motion and respect prefers-reduced-motion; preserve logical reading order across breakpoints.

## Imagery Direction

### Pairs With

deckle

### Summary

Torn-and-cut construction-paper collage: layered matte opaque papers with deckled edges and a faint fibre grain, each flat shape casting a soft short shadow onto the layer behind for gentle pop-up depth. Warm cream ground, bold simple friendly shapes, flat even light. Reserve quiet cream zones for type.

### Palette Hint

warm cream, poppy red-orange, meadow green, marigold yellow, soft teal (water only), espresso-brown ink

### Subjects

meadows and rolling hills, rivers and little boats, storybook forests, a rising sun, friendly child and animal cutouts, cosy villages, simple props (teapot, bicycle)

### Illustration Style

cut-paper collage in the tradition of hand-cut picture books; simple friendly rounded shapes; texture from sponged gouache and crayon on the papers before cutting

### Hero Image Direction

ONE full-bleed cut-paper scene with a generous open cream sky reserved upper-left for the display wordmark; a low round marigold sun and small character cutouts on the nearest hill

### Icon Style

simple line icons (1.8-2.2px stroke) or small cut-paper prop silhouettes; never emoji

shadcn/ui theme

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "diorama",
  "type": "registry:theme",
  "title": "Diorama shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#FAF2DF",
      "foreground": "#33241A",
      "card": "#FFFCF5",
      "card-foreground": "#33241A",
      "popover": "#FFFCF5",
      "popover-foreground": "#33241A",
      "primary": "#33241A",
      "primary-foreground": "#ffffff",
      "secondary": "#f4f4f5",
      "secondary-foreground": "#111111",
      "muted": "#705A3E",
      "muted-foreground": "#33241A",
      "accent": "#CE471E",
      "accent-foreground": "#ffffff",
      "destructive": "#BE3A28",
      "border": "#EAD9B6",
      "input": "#EAD9B6",
      "ring": "#CE471E",
      "chart-1": "#33241A",
      "chart-2": "#f4f4f5",
      "chart-3": "#CE471E",
      "chart-4": "#2E7D48",
      "chart-5": "#E08A2B",
      "sidebar": "#FFFCF5",
      "sidebar-foreground": "#33241A",
      "sidebar-primary": "#33241A",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#3E97B0",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#EAD9B6",
      "sidebar-ring": "#CE471E",
      "radius": "16px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#33241A",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#CE471E",
      "accent-foreground": "#ffffff",
      "destructive": "#BE3A28",
      "border": "#303642",
      "input": "#303642",
      "ring": "#CE471E",
      "chart-1": "#33241A",
      "chart-2": "#f4f4f5",
      "chart-3": "#CE471E",
      "chart-4": "#2E7D48",
      "chart-5": "#E08A2B",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#33241A",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#CE471E",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#CE471E",
      "radius": "16px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019fe2a2-6611-7923-bc68-0549219c7d1e",
    "slug": "diorama",
    "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",
        "accent2_ink",
        "accent_2",
        "accent_3",
        "accent_ink",
        "accent_soft",
        "bg",
        "border",
        "error",
        "info",
        "muted",
        "on_accent",
        "on_accent_dark",
        "success",
        "surface",
        "surface_solid",
        "text",
        "warning"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "heading_transform",
        "heading_weight",
        "letter_spacing",
        "line_height",
        "mono_font",
        "scale_ratio"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none"
      ],
      "shadows": [
        "lg",
        "md",
        "sm"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "borders": [
        "accent_width",
        "character",
        "default_width",
        "style"
      ],
      "motion": [
        "duration",
        "easing",
        "philosophy"
      ]
    }
  }
}
```

in the wild

embodiments

DESIGN.md

at a glance

Typography

headline-lgFraunces · 34px · 700

The quick brown fox jumps

headline-mdFraunces · 27px · 600

The quick brown fox jumps

body-mdAtkinson Hyperlegible · 18px · 400

The quick brown fox jumps

label-mdnone · 12px · 600

The quick brown fox jumps

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

button	ok
card	ok
input	ok

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: #FAF2DF;
  --foreground: #33241A;
  --card: #FFFCF5;
  --card-foreground: #33241A;
  --popover: #FFFCF5;
  --popover-foreground: #33241A;
  --primary: #33241A;
  --primary-foreground: #ffffff;
  --secondary: #f4f4f5;
  --secondary-foreground: #111111;
  --muted: #705A3E;
  --muted-foreground: #33241A;
  --accent: #CE471E;
  --accent-foreground: #ffffff;
  --destructive: #BE3A28;
  --border: #EAD9B6;
  --input: #EAD9B6;
  --ring: #CE471E;
  --chart-1: #33241A;
  --chart-2: #f4f4f5;
  --chart-3: #CE471E;
  --chart-4: #2E7D48;
  --chart-5: #E08A2B;
  --sidebar: #FFFCF5;
  --sidebar-foreground: #33241A;
  --sidebar-primary: #33241A;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #3E97B0;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #EAD9B6;
  --sidebar-ring: #CE471E;
  --radius: 16px;
}

.dark {
  --background: #0f1115;
  --foreground: #f8fafc;
  --card: #181b22;
  --card-foreground: #f8fafc;
  --popover: #181b22;
  --popover-foreground: #f8fafc;
  --primary: #33241A;
  --primary-foreground: #ffffff;
  --secondary: #252a33;
  --secondary-foreground: #f8fafc;
  --muted: #252a33;
  --muted-foreground: #a1a1aa;
  --accent: #CE471E;
  --accent-foreground: #ffffff;
  --destructive: #BE3A28;
  --border: #303642;
  --input: #303642;
  --ring: #CE471E;
  --chart-1: #33241A;
  --chart-2: #f4f4f5;
  --chart-3: #CE471E;
  --chart-4: #2E7D48;
  --chart-5: #E08A2B;
  --sidebar: #181b22;
  --sidebar-foreground: #f8fafc;
  --sidebar-primary: #33241A;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #CE471E;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #303642;
  --sidebar-ring: #CE471E;
  --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 DioramaShadcnKit() {
  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">Diorama</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 JSONstored

{
  "format": "shadcn-export-v1",
  "name": "diorama",
  "type": "registry:theme",
  "author": "katagami-agent",
  "language": "Diorama",
  "ground": "light",
  "meta": {
    "signature": "the Pop-up Rise — cut-paper planes stand up from warm cream paper; edges read by soft cast shadow, sequence by folio + page-pips; no ink outlines, no edge rails",
    "controlRadius": "16px",
    "notes": "Light-native cut-paper picture-book language. One gently-rounded radius (16px) on every container; true circles (avatars, sun, pips, radio) at 9999. Poppy, meadow and marigold on warm cream, used like highlighters. Fraunces read-aloud display over a fine Atkinson Hyperlegible body."
  },
  "cssVars": {
    "theme": {
      "font-display": "Fraunces, Georgia, serif",
      "font-sans": "Atkinson Hyperlegible, system-ui, sans-serif",
      "font-mono": "Atkinson Hyperlegible, system-ui, sans-serif",
      "radius": "1rem",
      "radius-md": "1rem",
      "radius-lg": "1rem",
      "radius-full": "9999px"
    },
    "light": {
      "background": "#FAF2DF",
      "foreground": "#33241A",
      "card": "#FFFCF5",
      "card-foreground": "#33241A",
      "popover": "#FFFCF5",
      "popover-foreground": "#33241A",
      "primary": "#CE471E",
      "primary-foreground": "#FFFDF8",
      "secondary": "#2E8C6A",
      "secondary-foreground": "#FFFDF8",
      "muted": "#F3E7CE",
      "muted-foreground": "#705A3E",
      "accent": "#F2B33D",
      "accent-foreground": "#33241A",
      "destructive": "#BE3A28",
      "destructive-foreground": "#FFFDF8",
      "success": "#2E7D48",
      "warning": "#E08A2B",
      "border": "#EAD9B6",
      "input": "#EAD9B6",
      "ring": "#CE471E",
      "chart-1": "#CE471E",
      "chart-2": "#2E8C6A",
      "chart-3": "#F2B33D",
      "chart-4": "#E08A2B",
      "chart-5": "#3E97B0"
    },
    "dark": {
      "background": "#2A1D14",
      "foreground": "#F7ECD8",
      "card": "#33251A",
      "card-foreground": "#F7ECD8",
      "popover": "#33251A",
      "popover-foreground": "#F7ECD8",
      "primary": "#E86A3F",
      "primary-foreground": "#2A1D14",
      "secondary": "#4FB088",
      "secondary-foreground": "#0F2419",
      "muted": "#3D2C1F",
      "muted-foreground": "#C6AE8C",
      "accent": "#F2B33D",
      "accent-foreground": "#2A1D14",
      "destructive": "#E06B57",
      "destructive-foreground": "#2A1D14",
      "success": "#5FB27B",
      "warning": "#E7A24A",
      "border": "#463525",
      "input": "#463525",
      "ring": "#E86A3F",
      "chart-1": "#E86A3F",
      "chart-2": "#4FB088",
      "chart-3": "#F2B33D",
      "chart-4": "#E7A24A",
      "chart-5": "#63B4CE"
    }
  },
  "fonts": {
    "google": "https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:ital,wght@0,400;0,700;1,400&family=Fraunces:opsz,wght@9..144,400..900&display=swap"
  }
}

component recipescompatibility fallback

# Diorama shadcn/ui Components

Artifact: `component-recipes-v1`
Author: `katagami-ui-projection`
Language ID: `en-019fe2a2-6611-7923-bc68-0549219c7d1e`
Slug: `diorama`

## Intent

Diorama is a modern picture-book language for interfaces that need to feel readable, warm and sequential for young children and the adults reading with them. It treats the screen as an opened storybook spread that stands up: each scene is a little paper theatre, cut and torn from warm construction paper and stacked into depth planes that rise off the page. A friendly round-faced character cutout anchors every beat so a pre-literate child can navigate by picture before word, and moving forward feels like turning a page rather than operating software. It keeps the soul of the storybook it descends from — cream paper, read-aloud rhythm, warm high-clarity contrast, handmade texture as a comprehension aid, one primary focus per view — and reconceives the expression as the Pop-up Rise.

## 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:

{
  "bg": "#FAF2DF",
  "surface": "#FFFCF5",
  "surface_solid": "#F3E7CE",
  "text": "#33241A",
  "muted": "#705A3E",
  "border": "#EAD9B6",
  "accent": "#CE471E",
  "accent_ink": "#A8380F",
  "accent_2": "#2E8C6A",
  "accent2_ink": "#1C6349",
  "accent_soft": "#F2B33D",
  "accent_3": "#F2B33D",
  "on_accent": "#FFFDF8",
  "on_accent_dark": "#33241A",
  "success": "#2E7D48",
  "warning": "#E08A2B",
  "error": "#BE3A28",
  "info": "#3E97B0"
}

Typography:

{
  "base_size": "17.5px",
  "body_font": "Atkinson Hyperlegible",
  "heading_font": "Fraunces",
  "mono_font": "none",
  "heading_weight": "700",
  "heading_transform": "none",
  "letter_spacing": "-0.01em",
  "line_height": "1.55",
  "scale_ratio": "1.25",
  "google_fonts_url": "https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:ital,wght@0,400;0,700;1,400&family=Fraunces:opsz,wght@9..144,400..900&display=swap"
}

## Visual character to preserve

- Opened-spread scenes stand up from warm cream paper in stacked cut-paper depth planes, each casting a soft shadow onto the layer behind.
- Torn deckled edges and a faint paper-fibre grain give every shape a hand-cut quality; a light rake shifts across the grain as a scene stands.
- Round-faced character cutouts and simple prop silhouettes anchor navigation before any text is read.
- Folio page-numbers, round page-pip trails, and a peeling top-right corner carry an unmistakable page-turn rhythm.
- Fraunces read-aloud display over a fine Atkinson Hyperlegible body; warm poppy, meadow and marigold papers used like highlighters on cream.

## ShadSync visual profile

{
  "family": "paper-collage",
  "material": "paper",
  "contour": "blob",
  "border": "solid",
  "underlay": true,
  "grain": true,
  "stickerBadges": false,
  "motion": "lift-rotate",
  "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/diorama/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: Let one cut-paper plane stand as the page thesis; give it the most rise and the shortest shadow.; Anchor every major scene with one friendly character or prop cutout, always paired with text.; Keep copy short, rhythmic and readable aloud; hold cream pauses between beats.; Reserve poppy-red, meadow-green and marigold for story objects and priority cues.; Read paper edges by their cast shadow; keep the paper's own colour doing the work.; Show sequence with a folio page-number, a row of round page-pips, and a corner peel.; Keep body at a fine 17.5px and let only the display carry read-aloud scale.
- Do not: Do not outline cards with ink or put a coloured edge rail or side stripe on any block.; Do not place textured paper or busy imagery directly under long body copy.; Do not rely on icon-only controls for core actions; keep touch targets child-sized.; Do not let more than three saturated papers compete in one region.; Do not make body text chunky, semibold or big; keep the mid-tier quiet.; Do not tilt every plane; the rise and a gentle paper tilt are accents, not a default.; Do not use neon, glassmorphism or slick tech gradients that erase the paper.

## 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 DioramaShadcnKit() {
  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">Diorama</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": "Low-to-medium for child comprehension: one standing story-plane, one supporting cluster, one clear next action per view.",
  "grid": "Desktop uses a 12-column max-1180px opened spread with 24px gutters and a soft centre gutter recalling the book's spine; tablet collapses to a considered two-up spread; mobile is one column with the action following the scene.",
  "breakpoints": {
    "mobile": "0-640px single page column (character, scene, choices, next-page cue)",
    "tablet": "641-1024px its own two-up spread, never the mobile column stretched wide",
    "desktop": "1025px+ twelve-column opened spread (max 1180px)"
  },
  "whitespace": "Cream margins of at least 20px mobile, 40px tablet, 64px desktop; 32-64px pauses between beats so the layout breathes like page turns.",
  "responsive": "Preserve the reading beats on smaller screens (scene, choices, read-aloud note, next-page). Planes may stack but keep their cast shadow and character anchor. Oversized display shrinks with clamp() and wraps; nav wraps, never spills."
}

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": "en-019fe2a2-6611-7923-bc68-0549219c7d1e",
    "name": "Diorama",
    "slug": "diorama"
  },
  "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": [
    "Opened-spread scenes stand up from warm cream paper in stacked cut-paper depth planes, each casting a soft shadow onto the layer behind.",
    "Torn deckled edges and a faint paper-fibre grain give every shape a hand-cut quality; a light rake shifts across the grain as a scene stands.",
    "Round-faced character cutouts and simple prop silhouettes anchor navigation before any text is read.",
    "Folio page-numbers, round page-pip trails, and a peeling top-right corner carry an unmistakable page-turn rhythm.",
    "Fraunces read-aloud display over a fine Atkinson Hyperlegible body; warm poppy, meadow and marigold papers used like highlighters on cream."
  ],
  "visualProfile": {
    "family": "paper-collage",
    "material": "paper",
    "contour": "default",
    "border": "solid",
    "underlay": true,
    "grain": true,
    "stickerBadges": false,
    "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": "Diorama 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": [
      "Let one cut-paper plane stand as the page thesis; give it the most rise and the shortest shadow.",
      "Anchor every major scene with one friendly character or prop cutout, always paired with text.",
      "Keep copy short, rhythmic and readable aloud; hold cream pauses between beats.",
      "Reserve poppy-red, meadow-green and marigold for story objects and priority cues.",
      "Read paper edges by their cast shadow; keep the paper's own colour doing the work.",
      "Show sequence with a folio page-number, a row of round page-pips, and a corner peel.",
      "Keep body at a fine 17.5px and let only the display carry read-aloud scale."
    ],
    "dont": [
      "Do not outline cards with ink or put a coloured edge rail or side stripe on any block.",
      "Do not place textured paper or busy imagery directly under long body copy.",
      "Do not rely on icon-only controls for core actions; keep touch targets child-sized.",
      "Do not let more than three saturated papers compete in one region.",
      "Do not make body text chunky, semibold or big; keep the mid-tier quiet.",
      "Do not tilt every plane; the rise and a gentle paper tilt are accents, not a default.",
      "Do not use neon, glassmorphism or slick tech gradients that erase the paper."
    ]
  }
}

built with

Palette

Credits · in the lineage of

Cut-paper collage picture-book illustrationTraditionTorn and cut construction-paper scenes with layered depth and visible paper texture.
Movable and pop-up book craftTraditionThe standing depth planes and the page-turn mechanics (folio, pips, corner peel).
Toy theatre / paper theatreTraditionScenes staged as cut-paper flats in a proscenium of depth.
Mid-century modern children's illustrationMovementBold simple friendly shapes and warm high-clarity colour.
Papier colleMovementThe collage technique of composing an image from cut and pasted papers.

A generated style is an aggregate of many influences — credit is given to the artists and traditions it draws on, not a claim of authorship.

remix lane

try a remix

Keep Diorama and swap a palette and an art style onto it. The landing & dashboard recolor live.

UI language · fixed

Diorama

Palette

Art style

Landing PageDiorama · Transformative teal + Adaptive violet · Cathode Ray

live preview · recolored + filled

More like this

Deckleshares cut-paper-collage · deckle-edge Maquetteshares picture-book · warm-cream Primershares early-literacy · read-aloud Aquarelleshares deckle-edge Decoupageshares deckle-edge Klaxonshares cut-paper-collage