back to gallery
design language·chromatic-critique-shell

Chromatic Critique Shell

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
A quiet Apple-clean product shell where vivid color is not garnish but the working medium: editorial swatches define state, compare options, mark decisions, and create memory inside restrained translucent neutral surfaces.
values
product-first neutralityauthored high-chroma color logiceditorial critique-wall hierarchyusable contrast and calm densitystructural rather than decorative accents
anti-values
×rainbow novelty or arbitrary confetti×generic dashboard panels with color trim×textbook color-wheel decoration×decorative side rails on cards or buttons
tokens
borders4 items
accent width
2px
character
soft graphite separators and color-matched focus rings used only around active controls or selected color fields
default width
1px
style
solid with selective inset box-shadow highlights
colors12 items
accent
#FFB000
background
#F5F3EE
border
#D9D6CE
error
#D84343
info
#2556F4
muted
#72716D
primary
#2556F4
secondary
#FF4F86
success
#1A9B68
surface
#FFFFFF
text
#171819
warning
#D88A00
motion3 items
duration
180ms
easing
cubic-bezier(.2,.8,.2,1)
philosophy
selected fields lift 2px and expand their painted area; state changes slide through color chips rather than fading generically
radii5 items
full
9999px
lg
24px
md
16px
none
0
sm
10px
shadows3 items
lg
0 32px 90px rgba(23,24,25,0.16)
md
0 18px 50px rgba(23,24,25,0.10)
sm
0 1px 2px rgba(23,24,25,0.05)
spacing2 items
base
8px
scale
4, 8, 12, 16, 24, 32, 48, 64, 96
surfaces3 items
bg pattern
quiet radial dot field at 14px spacing using low-opacity graphite points, masked behind content without square grid lines
card style
rounded neutral cards with thin translucent borders; color appears as inset fields or working cells, never as sideline strips
treatment
warm fog canvas with white/translucent graphite shells, inset top highlights, and sparse dotted calibration texture
typography8 items
base size
16px
body font
Chivo
google fonts url
https://fonts.googleapis.com/css2?family=Chivo:ital,wght@0,400;0,500;0,600;0,700;1,500&family=Fragment+Mono:ital@0;1&family=Instrument+Serif:ital@0;1&display=swap
heading font
Instrument Serif
letter spacing
-0.02em
line height
1.48
mono font
Fragment Mono
scale ratio
1.24
rules
composition
Use a product scene organized like a modern critique wall: a calm neutral shell, one dominant live artifact, one color-study cluster, and a few precise metadata panels with a deliberate off-grid overlap.
density
Balanced premium density: compact controls and tables are allowed, but unrelated groups get generous 48px to 96px breathing room against tight 4px to 8px internal label stacks.
hierarchy
Reserve the vivid colors for selected state, semantic comparison, and content-bearing swatches; typography and whitespace carry ordinary hierarchy so color moments remain memorable.
signature patterns
Painted-field controls: active buttons, tabs, selects, and badges fill with flat high-chroma rectangles that carry state and label content.Critique-pair swatches: complementary blue/pink and amber/graphite cells sit beside metrics to make comparison data spatial rather than decorative.Neutral glass shell: every panel uses translucent fog borders, inset white highlights, and restrained shadows to keep color fields feeling premium.Off-grid artifact stage: one product preview crosses the column grid with a subtle rotation-free overlap and becomes the visual anchor.Dot-calibration underlay: a low-contrast point texture appears only inside work surfaces and modals to suggest design-school measurement without boxes.
layout
breakpoints

mobile < 700px, tablet 700px-1060px, desktop > 1060px

grid
Desktop uses a 12-column shell with a 5-column artifact stage and 7-column critique stack; tablet collapses to two zones and mobile becomes a single editorial scroll.
whitespace

Use dramatic spacing contrast: 4px label ties, 12px field groups, 32px card sections, and 64px scene separations.

guidance
do
  • Use vivid color as selected state, swatch data, semantic comparison, or product preview material.
  • Keep all background and primary navigation surfaces neutral, translucent, and quiet.
  • Make each color pairing explain a decision, tension, or workflow state.
  • Use dotted calibration texture only at very low opacity and without square grid lines.
avoid
  • Do not create rainbow gradients, confetti, decorative blobs, or startup-style abstract art.
  • Do not add decorative color side rails, stripes, or left borders on cards, buttons, rows, or panels.
  • Do not let generic status colors be the only identity; color fields must organize the product workflow.
  • Do not use square grid wallpaper or textbook-page color theory diagrams.
katagami spec
# Chromatic Critique Shell

## Philosophy

A quiet Apple-clean product shell where vivid color is not garnish but the working medium: editorial swatches define state, compare options, mark decisions, and create memory inside restrained translucent neutral surfaces.

### Values

- product-first neutrality
- authored high-chroma color logic
- editorial critique-wall hierarchy
- usable contrast and calm density
- structural rather than decorative accents

### Anti-Values

- rainbow novelty or arbitrary confetti
- generic dashboard panels with color trim
- textbook color-wheel decoration
- decorative side rails on cards or buttons

### Visual Character

- Layer white, fog, and graphite panels with 1px translucent borders and glassy inset highlights over a warm neutral app canvas.
- Use rectangular painted color fields as real controls, comparison cells, tab states, and progress segments rather than background garnish.
- Build pages on an asymmetric critique-board grid where one oversized live artifact interrupts smaller measurement and note panels.
- Pair tight neo-grotesk body text with a high-contrast editorial serif for decision headlines and oversized color labels.
- Apply dotted non-boxy notebook texture only as a quiet calibration layer inside neutral surfaces, never as square grid wallpaper.

## Tokens

### Borders

- **Accent Width**: 2px
- **Character**: soft graphite separators and color-matched focus rings used only around active controls or selected color fields
- **Default Width**: 1px
- **Style**: solid with selective inset box-shadow highlights

### Colors

| Name | Value |
|------|-------|
| accent | `#FFB000` |
| background | `#F5F3EE` |
| border | `#D9D6CE` |
| error | `#D84343` |
| info | `#2556F4` |
| muted | `#72716D` |
| primary | `#2556F4` |
| secondary | `#FF4F86` |
| success | `#1A9B68` |
| surface | `#FFFFFF` |
| text | `#171819` |
| warning | `#D88A00` |

### Motion

- **Duration**: 180ms
- **Easing**: cubic-bezier(.2,.8,.2,1)
- **Philosophy**: selected fields lift 2px and expand their painted area; state changes slide through color chips rather than fading generically

### Radii

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

### Shadows

- **Lg**: 0 32px 90px rgba(23,24,25,0.16)
- **Md**: 0 18px 50px rgba(23,24,25,0.10)
- **Sm**: 0 1px 2px rgba(23,24,25,0.05)

### Spacing

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

### Surfaces

- **Bg Pattern**: quiet radial dot field at 14px spacing using low-opacity graphite points, masked behind content without square grid lines
- **Card Style**: rounded neutral cards with thin translucent borders; color appears as inset fields or working cells, never as sideline strips
- **Treatment**: warm fog canvas with white/translucent graphite shells, inset top highlights, and sparse dotted calibration texture

### Typography

- **Base Size**: 16px
- **Body Font**: Chivo
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Chivo:ital,wght@0,400;0,500;0,600;0,700;1,500&family=Fragment+Mono:ital@0;1&family=Instrument+Serif:ital@0;1&display=swap
- **Heading Font**: Instrument Serif
- **Letter Spacing**: -0.02em
- **Line Height**: 1.48
- **Mono Font**: Fragment Mono
- **Scale Ratio**: 1.24

## Rules

### Composition

Use a product scene organized like a modern critique wall: a calm neutral shell, one dominant live artifact, one color-study cluster, and a few precise metadata panels with a deliberate off-grid overlap.

### Density

Balanced premium density: compact controls and tables are allowed, but unrelated groups get generous 48px to 96px breathing room against tight 4px to 8px internal label stacks.

### Hierarchy

Reserve the vivid colors for selected state, semantic comparison, and content-bearing swatches; typography and whitespace carry ordinary hierarchy so color moments remain memorable.

### Signature Patterns

- Painted-field controls: active buttons, tabs, selects, and badges fill with flat high-chroma rectangles that carry state and label content.
- Critique-pair swatches: complementary blue/pink and amber/graphite cells sit beside metrics to make comparison data spatial rather than decorative.
- Neutral glass shell: every panel uses translucent fog borders, inset white highlights, and restrained shadows to keep color fields feeling premium.
- Off-grid artifact stage: one product preview crosses the column grid with a subtle rotation-free overlap and becomes the visual anchor.
- Dot-calibration underlay: a low-contrast point texture appears only inside work surfaces and modals to suggest design-school measurement without boxes.

## Layout

### Breakpoints

mobile < 700px, tablet 700px-1060px, desktop > 1060px

### Grid

Desktop uses a 12-column shell with a 5-column artifact stage and 7-column critique stack; tablet collapses to two zones and mobile becomes a single editorial scroll.

### Whitespace

Use dramatic spacing contrast: 4px label ties, 12px field groups, 32px card sections, and 64px scene separations.

## Guidance

### Do

- Use vivid color as selected state, swatch data, semantic comparison, or product preview material.
- Keep all background and primary navigation surfaces neutral, translucent, and quiet.
- Make each color pairing explain a decision, tension, or workflow state.
- Use dotted calibration texture only at very low opacity and without square grid lines.

### Don't

- Do not create rainbow gradients, confetti, decorative blobs, or startup-style abstract art.
- Do not add decorative color side rails, stripes, or left borders on cards, buttons, rows, or panels.
- Do not let generic status colors be the only identity; color fields must organize the product workflow.
- Do not use square grid wallpaper or textbook-page color theory diagrams.
DESIGN.md
---
version: "alpha"
name: "Chromatic Critique Shell"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  accent: "#FFB000"
  background: "#F5F3EE"
  border: "#D9D6CE"
  error: "#D84343"
  info: "#2556F4"
  muted: "#72716D"
  primary: "#2556F4"
  secondary: "#FF4F86"
  success: "#1A9B68"
  surface: "#FFFFFF"
  text: "#171819"
  warning: "#D88A00"
typography:
  headline-lg:
    fontFamily: "Instrument Serif"
    fontSize: "1.907rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  headline-md:
    fontFamily: "Instrument Serif"
    fontSize: "1.538rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: "Chivo"
    fontSize: "16px"
    fontWeight: 400
    lineHeight: 1.48
    letterSpacing: "-0.02em"
  label-md:
    fontFamily: "Fragment Mono"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
rounded:
  full: "9999px"
  lg: "24px"
  md: "16px"
  none: "0px"
  sm: "10px"
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-accent:
    backgroundColor: "{colors.accent}"
  color-reference-background:
    backgroundColor: "{colors.background}"
  color-reference-border:
    backgroundColor: "{colors.border}"
  color-reference-error:
    backgroundColor: "{colors.error}"
  color-reference-info:
    backgroundColor: "{colors.info}"
  color-reference-muted:
    backgroundColor: "{colors.muted}"
  color-reference-primary:
    backgroundColor: "{colors.primary}"
  color-reference-secondary:
    backgroundColor: "{colors.secondary}"
  color-reference-success:
    backgroundColor: "{colors.success}"
  color-reference-surface:
    backgroundColor: "{colors.surface}"
  color-reference-text:
    backgroundColor: "{colors.text}"
  color-reference-warning:
    backgroundColor: "{colors.warning}"
  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"
---

# Chromatic Critique Shell

## Overview

A quiet Apple-clean product shell where vivid color is not garnish but the working medium: editorial swatches define state, compare options, mark decisions, and create memory inside restrained translucent neutral surfaces.

### Values

- product-first neutrality
- authored high-chroma color logic
- editorial critique-wall hierarchy
- usable contrast and calm density
- structural rather than decorative accents

### Anti-Values

- rainbow novelty or arbitrary confetti
- generic dashboard panels with color trim
- textbook color-wheel decoration
- decorative side rails on cards or buttons

### Visual Character

- Layer white, fog, and graphite panels with 1px translucent borders and glassy inset highlights over a warm neutral app canvas.
- Use rectangular painted color fields as real controls, comparison cells, tab states, and progress segments rather than background garnish.
- Build pages on an asymmetric critique-board grid where one oversized live artifact interrupts smaller measurement and note panels.
- Pair tight neo-grotesk body text with a high-contrast editorial serif for decision headlines and oversized color labels.
- Apply dotted non-boxy notebook texture only as a quiet calibration layer inside neutral surfaces, never as square grid wallpaper.

## Colors

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

| Token | Value |
|-------|-------|
| accent | `#FFB000` |
| background | `#F5F3EE` |
| border | `#D9D6CE` |
| error | `#D84343` |
| info | `#2556F4` |
| muted | `#72716D` |
| primary | `#2556F4` |
| secondary | `#FF4F86` |
| success | `#1A9B68` |
| surface | `#FFFFFF` |
| text | `#171819` |
| warning | `#D88A00` |

## Typography

- **Headline-Lg**: Instrument Serif, 1.907rem, weight 700, line-height 1.1.
- **Headline-Md**: Instrument Serif, 1.538rem, weight 600, line-height 1.15.
- **Body-Md**: Chivo, 16px, weight 400, line-height 1.48.
- **Label-Md**: Fragment 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`

### Breakpoints

mobile < 700px, tablet 700px-1060px, desktop > 1060px

### Grid

Desktop uses a 12-column shell with a 5-column artifact stage and 7-column critique stack; tablet collapses to two zones and mobile becomes a single editorial scroll.

### Whitespace

Use dramatic spacing contrast: 4px label ties, 12px field groups, 32px card sections, and 64px scene separations.

## Elevation & Depth

### Shadows

- **Lg**: 0 32px 90px rgba(23,24,25,0.16)
- **Md**: 0 18px 50px rgba(23,24,25,0.10)
- **Sm**: 0 1px 2px rgba(23,24,25,0.05)

## Shapes

### Rounded

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

### Surfaces

- **Bg Pattern**: quiet radial dot field at 14px spacing using low-opacity graphite points, masked behind content without square grid lines
- **Card Style**: rounded neutral cards with thin translucent borders; color appears as inset fields or working cells, never as sideline strips
- **Treatment**: warm fog canvas with white/translucent graphite shells, inset top highlights, and sparse dotted calibration texture

### Borders

- **Accent Width**: 2px
- **Character**: soft graphite separators and color-matched focus rings used only around active controls or selected color fields
- **Default Width**: 1px
- **Style**: solid with selective inset box-shadow highlights

## Components

### Composition

Use a product scene organized like a modern critique wall: a calm neutral shell, one dominant live artifact, one color-study cluster, and a few precise metadata panels with a deliberate off-grid overlap.

### Density

Balanced premium density: compact controls and tables are allowed, but unrelated groups get generous 48px to 96px breathing room against tight 4px to 8px internal label stacks.

### Hierarchy

Reserve the vivid colors for selected state, semantic comparison, and content-bearing swatches; typography and whitespace carry ordinary hierarchy so color moments remain memorable.

### Signature Patterns

- Painted-field controls: active buttons, tabs, selects, and badges fill with flat high-chroma rectangles that carry state and label content.
- Critique-pair swatches: complementary blue/pink and amber/graphite cells sit beside metrics to make comparison data spatial rather than decorative.
- Neutral glass shell: every panel uses translucent fog borders, inset white highlights, and restrained shadows to keep color fields feeling premium.
- Off-grid artifact stage: one product preview crosses the column grid with a subtle rotation-free overlap and becomes the visual anchor.
- Dot-calibration underlay: a low-contrast point texture appears only inside work surfaces and modals to suggest design-school measurement without boxes.

## 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-019e45e4-ad5d-74d3-b72b-9867bf2b236d/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 Use vivid color as selected state, swatch data, semantic comparison, or product preview material.
- Do Keep all background and primary navigation surfaces neutral, translucent, and quiet.
- Do Make each color pairing explain a decision, tension, or workflow state.
- Do Use dotted calibration texture only at very low opacity and without square grid lines.
- Don't Do not create rainbow gradients, confetti, decorative blobs, or startup-style abstract art.
- Don't Do not add decorative color side rails, stripes, or left borders on cards, buttons, rows, or panels.
- Don't Do not let generic status colors be the only identity; color fields must organize the product workflow.
- Don't Do not use square grid wallpaper or textbook-page color theory diagrams.
shadcn/ui theme
```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "chromatic-critique-shell",
  "type": "registry:theme",
  "title": "Chromatic Critique Shell shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F5F3EE",
      "foreground": "#171819",
      "card": "#FFFFFF",
      "card-foreground": "#171819",
      "popover": "#FFFFFF",
      "popover-foreground": "#171819",
      "primary": "#2556F4",
      "primary-foreground": "#ffffff",
      "secondary": "#FF4F86",
      "secondary-foreground": "#ffffff",
      "muted": "#72716D",
      "muted-foreground": "#171819",
      "accent": "#FFB000",
      "accent-foreground": "#ffffff",
      "destructive": "#D84343",
      "border": "#D9D6CE",
      "input": "#D9D6CE",
      "ring": "#FFB000",
      "chart-1": "#2556F4",
      "chart-2": "#FF4F86",
      "chart-3": "#FFB000",
      "chart-4": "#1A9B68",
      "chart-5": "#D88A00",
      "sidebar": "#FFFFFF",
      "sidebar-foreground": "#171819",
      "sidebar-primary": "#2556F4",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#2556F4",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#D9D6CE",
      "sidebar-ring": "#FFB000",
      "radius": "16px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#2556F4",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#FFB000",
      "accent-foreground": "#ffffff",
      "destructive": "#D84343",
      "border": "#303642",
      "input": "#303642",
      "ring": "#FFB000",
      "chart-1": "#2556F4",
      "chart-2": "#FF4F86",
      "chart-3": "#FFB000",
      "chart-4": "#1A9B68",
      "chart-5": "#D88A00",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#2556F4",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#FFB000",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#FFB000",
      "radius": "16px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019e45e4-ad5d-74d3-b72b-9867bf2b236d",
    "slug": "chromatic-critique-shell",
    "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": {
      "borders": [
        "accent_width",
        "character",
        "default_width",
        "style"
      ],
      "colors": [
        "accent",
        "background",
        "border",
        "error",
        "info",
        "muted",
        "primary",
        "secondary",
        "success",
        "surface",
        "text",
        "warning"
      ],
      "motion": [
        "duration",
        "easing",
        "philosophy"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm"
      ],
      "shadows": [
        "lg",
        "md",
        "sm"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "letter_spacing",
        "line_height",
        "mono_font",
        "scale_ratio"
      ]
    }
  }
}
```
in the wild

embodiments

the full element showcase
embodiment · chromatic-critique-shell
DESIGN.md

at a glance

Palette

Typography

headline-lgInstrument Serif · 31px · 700

The quick brown fox jumps

headline-mdInstrument Serif · 25px · 600

The quick brown fox jumps

body-mdChivo · 16px · 400

The quick brown fox jumps

label-mdFragment 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

full9999px
lg24px
md16px
none0px
sm10px
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: #F5F3EE;
  --foreground: #171819;
  --card: #FFFFFF;
  --card-foreground: #171819;
  --popover: #FFFFFF;
  --popover-foreground: #171819;
  --primary: #2556F4;
  --primary-foreground: #ffffff;
  --secondary: #FF4F86;
  --secondary-foreground: #ffffff;
  --muted: #72716D;
  --muted-foreground: #171819;
  --accent: #FFB000;
  --accent-foreground: #ffffff;
  --destructive: #D84343;
  --border: #D9D6CE;
  --input: #D9D6CE;
  --ring: #FFB000;
  --chart-1: #2556F4;
  --chart-2: #FF4F86;
  --chart-3: #FFB000;
  --chart-4: #1A9B68;
  --chart-5: #D88A00;
  --sidebar: #FFFFFF;
  --sidebar-foreground: #171819;
  --sidebar-primary: #2556F4;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #2556F4;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #D9D6CE;
  --sidebar-ring: #FFB000;
  --radius: 16px;
}

.dark {
  --background: #0f1115;
  --foreground: #f8fafc;
  --card: #181b22;
  --card-foreground: #f8fafc;
  --popover: #181b22;
  --popover-foreground: #f8fafc;
  --primary: #2556F4;
  --primary-foreground: #ffffff;
  --secondary: #252a33;
  --secondary-foreground: #f8fafc;
  --muted: #252a33;
  --muted-foreground: #a1a1aa;
  --accent: #FFB000;
  --accent-foreground: #ffffff;
  --destructive: #D84343;
  --border: #303642;
  --input: #303642;
  --ring: #FFB000;
  --chart-1: #2556F4;
  --chart-2: #FF4F86;
  --chart-3: #FFB000;
  --chart-4: #1A9B68;
  --chart-5: #D88A00;
  --sidebar: #181b22;
  --sidebar-foreground: #f8fafc;
  --sidebar-primary: #2556F4;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #FFB000;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #303642;
  --sidebar-ring: #FFB000;
  --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 ChromaticCritiqueShellShadcnKit() {
  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">Chromatic Critique Shell</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 + verified
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "cssVars": {
    "dark": {
      "accent": "#FFB000",
      "accent-foreground": "#ffffff",
      "background": "#0f1115",
      "border": "#303642",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "chart-1": "#2556F4",
      "chart-2": "#FF4F86",
      "chart-3": "#FFB000",
      "chart-4": "#1A9B68",
      "chart-5": "#D88A00",
      "destructive": "#D84343",
      "foreground": "#f8fafc",
      "input": "#303642",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#2556F4",
      "primary-foreground": "#ffffff",
      "radius": "16px",
      "ring": "#FFB000",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "sidebar": "#181b22",
      "sidebar-accent": "#FFB000",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#2556F4",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-ring": "#FFB000"
    },
    "light": {
      "accent": "#FFB000",
      "accent-foreground": "#ffffff",
      "background": "#F5F3EE",
      "border": "#D9D6CE",
      "card": "#FFFFFF",
      "card-foreground": "#171819",
      "chart-1": "#2556F4",
      "chart-2": "#FF4F86",
      "chart-3": "#FFB000",
      "chart-4": "#1A9B68",
      "chart-5": "#D88A00",
      "destructive": "#D84343",
      "foreground": "#171819",
      "input": "#D9D6CE",
      "muted": "#72716D",
      "muted-foreground": "#171819",
      "popover": "#FFFFFF",
      "popover-foreground": "#171819",
      "primary": "#2556F4",
      "primary-foreground": "#ffffff",
      "radius": "16px",
      "ring": "#FFB000",
      "secondary": "#FF4F86",
      "secondary-foreground": "#ffffff",
      "sidebar": "#FFFFFF",
      "sidebar-accent": "#2556F4",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#D9D6CE",
      "sidebar-foreground": "#171819",
      "sidebar-primary": "#2556F4",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-ring": "#FFB000"
    },
    "theme": {}
  },
  "meta": {
    "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",
    "languageId": "en-019e45e4-ad5d-74d3-b72b-9867bf2b236d",
    "nativeTokenNames": {
      "borders": [
        "accent_width",
        "character",
        "default_width",
        "style"
      ],
      "colors": [
        "accent",
        "background",
        "border",
        "error",
        "info",
        "muted",
        "primary",
        "secondary",
        "success",
        "surface",
        "text",
        "warning"
      ],
      "motion": [
        "duration",
        "easing",
        "philosophy"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm"
      ],
      "shadows": [
        "lg",
        "md",
        "sm"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "letter_spacing",
        "line_height",
        "mono_font",
        "scale_ratio"
      ]
    },
    "slug": "chromatic-critique-shell",
    "source": "katagami"
  },
  "name": "chromatic-critique-shell",
  "title": "Chromatic Critique Shell shadcn Theme",
  "type": "registry:theme"
}
component recipescompatibility fallback
# Chromatic Critique Shell shadcn/ui Components

Artifact: `component-recipes-v1`
Author: `katagami-ui-projection`
Language ID: `en-019e45e4-ad5d-74d3-b72b-9867bf2b236d`
Slug: `chromatic-critique-shell`

## Intent

A quiet Apple-clean product shell where vivid color is not garnish but the working medium: editorial swatches define state, compare options, mark decisions, and create memory inside restrained translucent neutral surfaces.

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

{
  "accent": "#FFB000",
  "background": "#F5F3EE",
  "border": "#D9D6CE",
  "error": "#D84343",
  "info": "#2556F4",
  "muted": "#72716D",
  "primary": "#2556F4",
  "secondary": "#FF4F86",
  "success": "#1A9B68",
  "surface": "#FFFFFF",
  "text": "#171819",
  "warning": "#D88A00"
}

Typography:

{
  "base_size": "16px",
  "body_font": "Chivo",
  "google_fonts_url": "https://fonts.googleapis.com/css2?family=Chivo:ital,wght@0,400;0,500;0,600;0,700;1,500&family=Fragment+Mono:ital@0;1&family=Instrument+Serif:ital@0;1&display=swap",
  "heading_font": "Instrument Serif",
  "letter_spacing": "-0.02em",
  "line_height": 1.48,
  "mono_font": "Fragment Mono",
  "scale_ratio": 1.24
}

## Visual character to preserve

- Layer white, fog, and graphite panels with 1px translucent borders and glassy inset highlights over a warm neutral app canvas.
- Use rectangular painted color fields as real controls, comparison cells, tab states, and progress segments rather than background garnish.
- Build pages on an asymmetric critique-board grid where one oversized live artifact interrupts smaller measurement and note panels.
- Pair tight neo-grotesk body text with a high-contrast editorial serif for decision headlines and oversized color labels.
- Apply dotted non-boxy notebook texture only as a quiet calibration layer inside neutral surfaces, never as square grid wallpaper.

## ShadSync visual profile

{
  "family": "paper-collage",
  "material": "paper",
  "contour": "default",
  "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/chromatic-critique-shell/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: Use vivid color as selected state, swatch data, semantic comparison, or product preview material.; Keep all background and primary navigation surfaces neutral, translucent, and quiet.; Make each color pairing explain a decision, tension, or workflow state.; Use dotted calibration texture only at very low opacity and without square grid lines.
- Do not: Do not create rainbow gradients, confetti, decorative blobs, or startup-style abstract art.; Do not add decorative color side rails, stripes, or left borders on cards, buttons, rows, or panels.; Do not let generic status colors be the only identity; color fields must organize the product workflow.; Do not use square grid wallpaper or textbook-page color theory diagrams.

## 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 ChromaticCritiqueShellShadcnKit() {
  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">Chromatic Critique Shell</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

{
  "breakpoints": "mobile < 700px, tablet 700px-1060px, desktop > 1060px",
  "grid": "Desktop uses a 12-column shell with a 5-column artifact stage and 7-column critique stack; tablet collapses to two zones and mobile becomes a single editorial scroll.",
  "whitespace": "Use dramatic spacing contrast: 4px label ties, 12px field groups, 32px card sections, and 64px scene separations."
}
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-019e45e4-ad5d-74d3-b72b-9867bf2b236d",
    "name": "Chromatic Critique Shell",
    "slug": "chromatic-critique-shell"
  },
  "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": [
    "Layer white, fog, and graphite panels with 1px translucent borders and glassy inset highlights over a warm neutral app canvas.",
    "Use rectangular painted color fields as real controls, comparison cells, tab states, and progress segments rather than background garnish.",
    "Build pages on an asymmetric critique-board grid where one oversized live artifact interrupts smaller measurement and note panels.",
    "Pair tight neo-grotesk body text with a high-contrast editorial serif for decision headlines and oversized color labels.",
    "Apply dotted non-boxy notebook texture only as a quiet calibration layer inside neutral surfaces, never as square grid wallpaper."
  ],
  "visualProfile": {
    "family": "paper-collage",
    "material": "paper",
    "contour": "default",
    "border": "solid",
    "underlay": true,
    "grain": true,
    "stickerBadges": true,
    "motion": "still",
    "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": "Chromatic Critique Shell 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": [
      "Use vivid color as selected state, swatch data, semantic comparison, or product preview material.",
      "Keep all background and primary navigation surfaces neutral, translucent, and quiet.",
      "Make each color pairing explain a decision, tension, or workflow state.",
      "Use dotted calibration texture only at very low opacity and without square grid lines."
    ],
    "dont": [
      "Do not create rainbow gradients, confetti, decorative blobs, or startup-style abstract art.",
      "Do not add decorative color side rails, stripes, or left borders on cards, buttons, rows, or panels.",
      "Do not let generic status colors be the only identity; color fields must organize the product workflow.",
      "Do not use square grid wallpaper or textbook-page color theory diagrams."
    ]
  }
}
related

More like this