design language·semantic-control-plane

Semantic Control Plane

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

Draft

Download DESIGN.md

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

the spec

specification

philosophy

summary

Semantic Control Plane is a production-first palette language for complex SaaS environments where dense data, governance workflows, and live operational states must remain calm, legible, and unambiguous across light and dark modes.

values

Neutral hierarchy before brand expressionSemantic color that always maps to product meaningAccessible contrast with icon and text redundancyWarm/cool gray balance for long-session comfortToken readiness for primitive ramps, aliases, and chart safety

anti-values

×Decorative chroma in dense tables or operational panels×One-off hex values outside named primitive or semantic tokens×Status meaning communicated by hue alone×Dark-mode overrides that drop role coverage or contrast

tokens

borders4 items

accent width: 3px
character: low-contrast neutral gridlines with semantic left rails for stateful modules
default width: 1px
style: solid

colors12 items

accent

#0E7490

background

#F7F8FA

border

#D7DCE2

error

#B42318

info

#175CD3

muted

#6B7280

primary

#1D4ED8

secondary

#475569

success

#027A48

surface

#FFFFFF

text

#111827

warning

#B54708

motion3 items

duration: 140ms
easing: cubic-bezier(0.2, 0, 0, 1)
philosophy: instant operational feedback; color and elevation changes are brief, never playful

radii5 items

full: 9999px
lg: 12px
md: 8px
none: 0
sm: 4px

shadows3 items

lg: 0 18px 48px rgba(15,23,42,0.12)
md: 0 8px 24px rgba(15,23,42,0.08)
sm: 0 1px 2px rgba(15,23,42,0.06)

spacing2 items

base: 8px
scale: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64

surfaces3 items

bg pattern: subtle 24px neutral grid only in the command header and never behind table content
card style: flat white or near-black panels separated by 1px borders, not floating glass
treatment: matte neutral planes with separate warm reading panels and cool navigation chrome

typography8 items

base size: 16px
body font: Inter
google fonts url: https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@500;600;700&family=Inter:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500;600&display=swap
heading font: Instrument Sans
letter spacing: -0.01em
line height: 1.5
mono font: IBM Plex Mono
scale ratio: 1.2

rules

composition

Build screens as an operations console: persistent left rail, compact command header, primary work table, and right-side evidence panel with semantic status cards.

density

High density is acceptable when rows keep 40-48px height, controls align to an 8px grid, and every status has a text label plus an icon marker.

hierarchy

Use size sparingly; hierarchy comes from surface role, border weight, tabular numeric alignment, and whether an element is neutral, brand-active, or semantic-critical.

signature patterns

Semantic rail cards combine a 3px status border, pale token background, icon dot, and explicit label to support colorblind and high-contrast reading.Dual-neutral surfaces alternate cool chrome for navigation with warm data panels for prolonged reading, expressed through CSS variables rather than ad hoc hex values.Primary action and focus states use a single trusted blue ring while secondary actions remain gray, reducing decorative chroma in dense workflows.Data tables use tabular numerals, thin separators, status badges with text, and color-safe chart swatches limited to named semantic and chart tokens.

layout

breakpoints

mobile 375px, tablet 768px, desktop 1200px, wide 1440px

grid

12-column desktop grid with a 280px navigation rail, fluid center work area, and 360px evidence panel; tablet collapses to two columns and mobile stacks command, table, and evidence.

whitespace

Compact 8px rhythm in tables and controls, 16-24px rhythm between modules, and deliberate empty neutral gutters around high-risk decisions.

guidance

Tokenize primitive ramps 50-1000 and expose semantic aliases for foreground, background, border, focus, and state roles.
Use icons, labels, and contrast-tested backgrounds for success, warning, error, and info states.
Keep charts colorblind-safe by combining hue, label, stroke pattern, and direct annotation.
Maintain equal role coverage in light and dark themes before adding brand flourishes.

avoid

Do not put decorative gradients, rainbow badges, or novelty chroma inside dense data tables.
Do not communicate status by color alone or use pale text on tinted backgrounds without contrast checks.
Do not introduce raw hex values in product code outside primitive token definitions.
Do not create dark-mode-only exceptions that change semantic meaning.

katagami spec

# Semantic Control Plane

## Philosophy

Semantic Control Plane is a production-first palette language for complex SaaS environments where dense data, governance workflows, and live operational states must remain calm, legible, and unambiguous across light and dark modes.

### Values

- Neutral hierarchy before brand expression
- Semantic color that always maps to product meaning
- Accessible contrast with icon and text redundancy
- Warm/cool gray balance for long-session comfort
- Token readiness for primitive ramps, aliases, and chart safety

### Anti-Values

- Decorative chroma in dense tables or operational panels
- One-off hex values outside named primitive or semantic tokens
- Status meaning communicated by hue alone
- Dark-mode overrides that drop role coverage or contrast

### Visual Character

- CSS uses paired cool and warm neutral custom properties, with cool grays for chrome and warm grays for reading surfaces so hierarchy is structural rather than colorful.
- Every status block is a two-part CSS pattern: a tinted low-chroma background plus a dark edge stripe and inline icon slot, preventing hue-only communication.
- Brand blue appears through restrained border accents, focus rings, active tabs, and one primary action only; tables and cards stay neutral by default.
- Light and dark themes share the same role names in CSS variables, including surface, panel, field, semantic-soft, semantic-line, and semantic-text roles.
- Dense data regions use thin gridlines, tabular numerals, compact spacing, and no gradients except a barely visible neutral underlay for the command header.

## Tokens

### Borders

- **Accent Width**: 3px
- **Character**: low-contrast neutral gridlines with semantic left rails for stateful modules
- **Default Width**: 1px
- **Style**: solid

### Colors

| Name | Value |
|------|-------|
| accent | `#0E7490` |
| background | `#F7F8FA` |
| border | `#D7DCE2` |
| error | `#B42318` |
| info | `#175CD3` |
| muted | `#6B7280` |
| primary | `#1D4ED8` |
| secondary | `#475569` |
| success | `#027A48` |
| surface | `#FFFFFF` |
| text | `#111827` |
| warning | `#B54708` |

### Motion

- **Duration**: 140ms
- **Easing**: cubic-bezier(0.2, 0, 0, 1)
- **Philosophy**: instant operational feedback; color and elevation changes are brief, never playful

### Radii

- **Full**: 9999px
- **Lg**: 12px
- **Md**: 8px
- **None**: 0
- **Sm**: 4px

### Shadows

- **Lg**: 0 18px 48px rgba(15,23,42,0.12)
- **Md**: 0 8px 24px rgba(15,23,42,0.08)
- **Sm**: 0 1px 2px rgba(15,23,42,0.06)

### Spacing

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

### Surfaces

- **Bg Pattern**: subtle 24px neutral grid only in the command header and never behind table content
- **Card Style**: flat white or near-black panels separated by 1px borders, not floating glass
- **Treatment**: matte neutral planes with separate warm reading panels and cool navigation chrome

### Typography

- **Base Size**: 16px
- **Body Font**: Inter
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@500;600;700&family=Inter:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500;600&display=swap
- **Heading Font**: Instrument Sans
- **Letter Spacing**: -0.01em
- **Line Height**: 1.5
- **Mono Font**: IBM Plex Mono
- **Scale Ratio**: 1.2

## Rules

### Composition

Build screens as an operations console: persistent left rail, compact command header, primary work table, and right-side evidence panel with semantic status cards.

### Density

High density is acceptable when rows keep 40-48px height, controls align to an 8px grid, and every status has a text label plus an icon marker.

### Hierarchy

Use size sparingly; hierarchy comes from surface role, border weight, tabular numeric alignment, and whether an element is neutral, brand-active, or semantic-critical.

### Signature Patterns

- Semantic rail cards combine a 3px status border, pale token background, icon dot, and explicit label to support colorblind and high-contrast reading.
- Dual-neutral surfaces alternate cool chrome for navigation with warm data panels for prolonged reading, expressed through CSS variables rather than ad hoc hex values.
- Primary action and focus states use a single trusted blue ring while secondary actions remain gray, reducing decorative chroma in dense workflows.
- Data tables use tabular numerals, thin separators, status badges with text, and color-safe chart swatches limited to named semantic and chart tokens.

## Layout

### Breakpoints

mobile 375px, tablet 768px, desktop 1200px, wide 1440px

### Grid

12-column desktop grid with a 280px navigation rail, fluid center work area, and 360px evidence panel; tablet collapses to two columns and mobile stacks command, table, and evidence.

### Whitespace

Compact 8px rhythm in tables and controls, 16-24px rhythm between modules, and deliberate empty neutral gutters around high-risk decisions.

## Guidance

### Do

- Tokenize primitive ramps 50-1000 and expose semantic aliases for foreground, background, border, focus, and state roles.
- Use icons, labels, and contrast-tested backgrounds for success, warning, error, and info states.
- Keep charts colorblind-safe by combining hue, label, stroke pattern, and direct annotation.
- Maintain equal role coverage in light and dark themes before adding brand flourishes.

### Don't

- Do not put decorative gradients, rainbow badges, or novelty chroma inside dense data tables.
- Do not communicate status by color alone or use pale text on tinted backgrounds without contrast checks.
- Do not introduce raw hex values in product code outside primitive token definitions.
- Do not create dark-mode-only exceptions that change semantic meaning.

DESIGN.md

---
version: "alpha"
name: "Semantic Control Plane"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  accent: "#0E7490"
  background: "#F7F8FA"
  border: "#D7DCE2"
  error: "#B42318"
  info: "#175CD3"
  muted: "#6B7280"
  primary: "#1D4ED8"
  secondary: "#475569"
  success: "#027A48"
  surface: "#FFFFFF"
  text: "#111827"
  warning: "#B54708"
typography:
  headline-lg:
    fontFamily: "Instrument Sans"
    fontSize: "1.728rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.01em"
  headline-md:
    fontFamily: "Instrument Sans"
    fontSize: "1.44rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.01em"
  body-md:
    fontFamily: "Inter"
    fontSize: "16px"
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: "-0.01em"
  label-md:
    fontFamily: "IBM Plex Mono"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
rounded:
  full: "9999px"
  lg: "12px"
  md: "8px"
  none: "0px"
  sm: "4px"
spacing:
  base: "8px"
  xs: "4px"
  sm: "8px"
  md: "12px"
  lg: "16px"
  xl: "20px"
  2xl: "24px"
  3xl: "32px"
  4xl: "40px"
  step-8: "48px"
  step-9: "64px"
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"
---

# Semantic Control Plane

## Overview

Semantic Control Plane is a production-first palette language for complex SaaS environments where dense data, governance workflows, and live operational states must remain calm, legible, and unambiguous across light and dark modes.

### Values

- Neutral hierarchy before brand expression
- Semantic color that always maps to product meaning
- Accessible contrast with icon and text redundancy
- Warm/cool gray balance for long-session comfort
- Token readiness for primitive ramps, aliases, and chart safety

### Anti-Values

- Decorative chroma in dense tables or operational panels
- One-off hex values outside named primitive or semantic tokens
- Status meaning communicated by hue alone
- Dark-mode overrides that drop role coverage or contrast

### Visual Character

- CSS uses paired cool and warm neutral custom properties, with cool grays for chrome and warm grays for reading surfaces so hierarchy is structural rather than colorful.
- Every status block is a two-part CSS pattern: a tinted low-chroma background plus a dark edge stripe and inline icon slot, preventing hue-only communication.
- Brand blue appears through restrained border accents, focus rings, active tabs, and one primary action only; tables and cards stay neutral by default.
- Light and dark themes share the same role names in CSS variables, including surface, panel, field, semantic-soft, semantic-line, and semantic-text roles.
- Dense data regions use thin gridlines, tabular numerals, compact spacing, and no gradients except a barely visible neutral underlay for the command header.

## 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 | `#0E7490` |
| background | `#F7F8FA` |
| border | `#D7DCE2` |
| error | `#B42318` |
| info | `#175CD3` |
| muted | `#6B7280` |
| primary | `#1D4ED8` |
| secondary | `#475569` |
| success | `#027A48` |
| surface | `#FFFFFF` |
| text | `#111827` |
| warning | `#B54708` |

## Typography

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

## Layout

### Spacing Tokens

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

### Breakpoints

mobile 375px, tablet 768px, desktop 1200px, wide 1440px

### Grid

12-column desktop grid with a 280px navigation rail, fluid center work area, and 360px evidence panel; tablet collapses to two columns and mobile stacks command, table, and evidence.

### Whitespace

Compact 8px rhythm in tables and controls, 16-24px rhythm between modules, and deliberate empty neutral gutters around high-risk decisions.

## Elevation & Depth

### Shadows

- **Lg**: 0 18px 48px rgba(15,23,42,0.12)
- **Md**: 0 8px 24px rgba(15,23,42,0.08)
- **Sm**: 0 1px 2px rgba(15,23,42,0.06)

## Shapes

### Rounded

- **Full**: `9999px`
- **Lg**: `12px`
- **Md**: `8px`
- **None**: `0px`
- **Sm**: `4px`

### Surfaces

- **Bg Pattern**: subtle 24px neutral grid only in the command header and never behind table content
- **Card Style**: flat white or near-black panels separated by 1px borders, not floating glass
- **Treatment**: matte neutral planes with separate warm reading panels and cool navigation chrome

### Borders

- **Accent Width**: 3px
- **Character**: low-contrast neutral gridlines with semantic left rails for stateful modules
- **Default Width**: 1px
- **Style**: solid

## Components

### Composition

Build screens as an operations console: persistent left rail, compact command header, primary work table, and right-side evidence panel with semantic status cards.

### Density

High density is acceptable when rows keep 40-48px height, controls align to an 8px grid, and every status has a text label plus an icon marker.

### Hierarchy

Use size sparingly; hierarchy comes from surface role, border weight, tabular numeric alignment, and whether an element is neutral, brand-active, or semantic-critical.

### Signature Patterns

- Semantic rail cards combine a 3px status border, pale token background, icon dot, and explicit label to support colorblind and high-contrast reading.
- Dual-neutral surfaces alternate cool chrome for navigation with warm data panels for prolonged reading, expressed through CSS variables rather than ad hoc hex values.
- Primary action and focus states use a single trusted blue ring while secondary actions remain gray, reducing decorative chroma in dense workflows.
- Data tables use tabular numerals, thin separators, status badges with text, and color-safe chart swatches limited to named semantic and chart tokens.

## 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-019ea9b1-a837-7e80-a285-697ce8356ab4/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 Tokenize primitive ramps 50-1000 and expose semantic aliases for foreground, background, border, focus, and state roles.
- Do Use icons, labels, and contrast-tested backgrounds for success, warning, error, and info states.
- Do Keep charts colorblind-safe by combining hue, label, stroke pattern, and direct annotation.
- Do Maintain equal role coverage in light and dark themes before adding brand flourishes.
- Don't Do not put decorative gradients, rainbow badges, or novelty chroma inside dense data tables.
- Don't Do not communicate status by color alone or use pale text on tinted backgrounds without contrast checks.
- Don't Do not introduce raw hex values in product code outside primitive token definitions.
- Don't Do not create dark-mode-only exceptions that change semantic meaning.

shadcn/ui theme

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "semantic-control-plane",
  "type": "registry:theme",
  "title": "Semantic Control Plane shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F7F8FA",
      "foreground": "#111827",
      "card": "#FFFFFF",
      "card-foreground": "#111827",
      "popover": "#FFFFFF",
      "popover-foreground": "#111827",
      "primary": "#1D4ED8",
      "primary-foreground": "#ffffff",
      "secondary": "#475569",
      "secondary-foreground": "#ffffff",
      "muted": "#6B7280",
      "muted-foreground": "#111827",
      "accent": "#0E7490",
      "accent-foreground": "#ffffff",
      "destructive": "#B42318",
      "border": "#D7DCE2",
      "input": "#D7DCE2",
      "ring": "#0E7490",
      "chart-1": "#1D4ED8",
      "chart-2": "#475569",
      "chart-3": "#0E7490",
      "chart-4": "#027A48",
      "chart-5": "#B54708",
      "sidebar": "#FFFFFF",
      "sidebar-foreground": "#111827",
      "sidebar-primary": "#1D4ED8",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#175CD3",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#D7DCE2",
      "sidebar-ring": "#0E7490",
      "radius": "8px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#1D4ED8",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#0E7490",
      "accent-foreground": "#ffffff",
      "destructive": "#B42318",
      "border": "#303642",
      "input": "#303642",
      "ring": "#0E7490",
      "chart-1": "#1D4ED8",
      "chart-2": "#475569",
      "chart-3": "#0E7490",
      "chart-4": "#027A48",
      "chart-5": "#B54708",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#1D4ED8",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#0E7490",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#0E7490",
      "radius": "8px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019ea9b1-a837-7e80-a285-697ce8356ab4",
    "slug": "semantic-control-plane",
    "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 · semantic-control-plane

DESIGN.md

at a glance

Palette

Typography

headline-lgInstrument Sans · 28px · 700

The quick brown fox jumps

headline-mdInstrument Sans · 23px · 600

The quick brown fox jumps

body-mdInter · 16px · 400

The quick brown fox jumps

label-mdIBM Plex Mono · 12px · 600

The quick brown fox jumps

Components

New

Card title

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

Spacing

base8px
xs4px
sm8px
md12px
lg16px
xl20px
2xl24px
3xl32px
4xl40px
step-848px
step-964px

Shape

full9999px

lg12px

md8px

none0px

sm4px

shadcn/ui

implementation kit

needs agent-authored kitstored

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: #F7F8FA;
  --foreground: #111827;
  --card: #FFFFFF;
  --card-foreground: #111827;
  --popover: #FFFFFF;
  --popover-foreground: #111827;
  --primary: #1D4ED8;
  --primary-foreground: #ffffff;
  --secondary: #475569;
  --secondary-foreground: #ffffff;
  --muted: #6B7280;
  --muted-foreground: #111827;
  --accent: #0E7490;
  --accent-foreground: #ffffff;
  --destructive: #B42318;
  --border: #D7DCE2;
  --input: #D7DCE2;
  --ring: #0E7490;
  --chart-1: #1D4ED8;
  --chart-2: #475569;
  --chart-3: #0E7490;
  --chart-4: #027A48;
  --chart-5: #B54708;
  --sidebar: #FFFFFF;
  --sidebar-foreground: #111827;
  --sidebar-primary: #1D4ED8;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #175CD3;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #D7DCE2;
  --sidebar-ring: #0E7490;
  --radius: 8px;
}

.dark {
  --background: #0f1115;
  --foreground: #f8fafc;
  --card: #181b22;
  --card-foreground: #f8fafc;
  --popover: #181b22;
  --popover-foreground: #f8fafc;
  --primary: #1D4ED8;
  --primary-foreground: #ffffff;
  --secondary: #252a33;
  --secondary-foreground: #f8fafc;
  --muted: #252a33;
  --muted-foreground: #a1a1aa;
  --accent: #0E7490;
  --accent-foreground: #ffffff;
  --destructive: #B42318;
  --border: #303642;
  --input: #303642;
  --ring: #0E7490;
  --chart-1: #1D4ED8;
  --chart-2: #475569;
  --chart-3: #0E7490;
  --chart-4: #027A48;
  --chart-5: #B54708;
  --sidebar: #181b22;
  --sidebar-foreground: #f8fafc;
  --sidebar-primary: #1D4ED8;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #0E7490;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #303642;
  --sidebar-ring: #0E7490;
  --radius: 8px;
}

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 SemanticControlPlaneShadcnKit() {
  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">Semantic Control Plane</h2>
          <p className="mt-1 max-w-xl text-sm text-muted-foreground">
            Use the Katagami registry theme, then compose these shadcn primitives
            with the language-specific component recipes.
          </p>
        </div>
        <Button>Apply theme</Button>
      </div>

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

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

theme JSONcompatibility fallback

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "semantic-control-plane",
  "type": "registry:theme",
  "title": "Semantic Control Plane shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F7F8FA",
      "foreground": "#111827",
      "card": "#FFFFFF",
      "card-foreground": "#111827",
      "popover": "#FFFFFF",
      "popover-foreground": "#111827",
      "primary": "#1D4ED8",
      "primary-foreground": "#ffffff",
      "secondary": "#475569",
      "secondary-foreground": "#ffffff",
      "muted": "#6B7280",
      "muted-foreground": "#111827",
      "accent": "#0E7490",
      "accent-foreground": "#ffffff",
      "destructive": "#B42318",
      "border": "#D7DCE2",
      "input": "#D7DCE2",
      "ring": "#0E7490",
      "chart-1": "#1D4ED8",
      "chart-2": "#475569",
      "chart-3": "#0E7490",
      "chart-4": "#027A48",
      "chart-5": "#B54708",
      "sidebar": "#FFFFFF",
      "sidebar-foreground": "#111827",
      "sidebar-primary": "#1D4ED8",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#175CD3",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#D7DCE2",
      "sidebar-ring": "#0E7490",
      "radius": "8px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#1D4ED8",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#0E7490",
      "accent-foreground": "#ffffff",
      "destructive": "#B42318",
      "border": "#303642",
      "input": "#303642",
      "ring": "#0E7490",
      "chart-1": "#1D4ED8",
      "chart-2": "#475569",
      "chart-3": "#0E7490",
      "chart-4": "#027A48",
      "chart-5": "#B54708",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#1D4ED8",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#0E7490",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#0E7490",
      "radius": "8px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019ea9b1-a837-7e80-a285-697ce8356ab4",
    "slug": "semantic-control-plane",
    "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"
      ]
    }
  }
}

component recipesstored

# Semantic Control Plane shadcn/ui Components
Author: `katagami-agent`

## Intent
Translate a disciplined enterprise semantic palette into shadcn/ui screens where neutral hierarchy, status redundancy, and token role parity are visible.

## Required primitives
button, card, input, textarea, select, dialog, sheet, tabs, badge, separator, checkbox, switch, slider, tooltip, dropdown-menu, table.

## Token cues
Use brand blue only for primary action, focus ring, selected tab, and active navigation. Use warm/cool neutral surfaces for reading versus chrome. Status recipes always pair soft background, border, icon/dot, and text label.

## Visual character to preserve
Cool navigation chrome, warm reading panels, 1px borders, 3px semantic rails, compact table rhythm, tabular numerals, and no decorative chroma in dense rows.

## ShadSync visual profile
family: enterprise-semantic; material: matte-neutral; contour: measured-radius; border: one-pixel-plus-status-rail; underlay: command-grid; grain: false; stickerBadges: false; motion: instant-operational; density: compact; accents: trusted-blue-and-semantic-ramps.

## Signature component recipes
- button: default neutral outline; primary uses blue fill; destructive must include icon text and error token.
- card: flat bordered matte panel, radius 12px, optional 3px left semantic rail for stateful cards.
- input: cool neutral field, 1px border, blue focus ring; never use colored field fills for decoration.
- textarea: same as input with warm reading background for notes.
- select: neutral trigger with compact height and explicit selected label.
- dialog: white/warm panel with neutral overlay and one blue confirmation action.
- sheet: evidence panel style with left border and stacked semantic rail cards.
- tabs: selected tab uses 3px blue underline, not filled pills.
- badge: status badges include dot/icon and label, with soft bg, line, and dark text.
- separator: 1px cool neutral line; no gradient separators.
- checkbox: blue check only when selected; label remains primary communicator.
- switch: neutral track, blue active thumb/track, visible text adjacent.
- slider: neutral track, blue filled range, mono numeric output.
- tooltip: dark neutral surface, high-contrast text, short operational copy.
- dropdown-menu: white bordered list, active item blue text on neutral background.
- table: 40-48px rows, mono numeric cells, thin separators, status badge text required.

## Preview shots
application-shell, detail-editor, data-operations.

## Implementation contract
Import local primitives from `@/components/ui/*`; do not invent a second component system. Preserve semantic redundancy and token role names in all states.

## Copy-paste component example
```tsx
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { Badge } from "@/components/ui/badge"
import { Input } from "@/components/ui/input"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

export function SemanticAuditCard() {
  return (
    <Card className="border border-border bg-card shadow-none">
      <CardHeader className="border-l-[3px] border-l-amber-700">
        <CardTitle>Warning ramp requires label redundancy</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <Badge variant="outline" className="gap-2 border-amber-300 bg-amber-50 text-amber-800"><span className="h-2 w-2 rounded-full bg-amber-700" />Needs label</Badge>
        <Input value="semantic.status.warning.bg" readOnly />
        <Table><TableHeader><TableRow><TableHead>Token</TableHead><TableHead>Contrast</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>warning.fg</TableCell><TableCell className="font-mono">5.4:1</TableCell></TableRow></TableBody></Table>
        <Button>Approve semantic alias</Button>
      </CardContent>
    </Card>
  )
}
```

preview shotsstored

{
  "artifact": "katagami:shadcn-preview-shots",
  "author": "katagami-agent",
  "componentRecipes": [
    "button",
    "card",
    "input",
    "textarea",
    "select",
    "dialog",
    "sheet",
    "tabs",
    "badge",
    "separator",
    "checkbox",
    "switch",
    "slider",
    "tooltip",
    "dropdown-menu",
    "table"
  ],
  "generatedBy": "katagami-agent",
  "renderable": true,
  "requiresVisualProfile": true,
  "schema": "katagami:shadcn-preview-shots/renderable-v1",
  "shots": [
    {
      "avoid": [
        "decorative gradients in table",
        "color-only status"
      ],
      "composition": "Left rail, command header, metric cards, and audit table with semantic badges.",
      "id": "application-shell",
      "mustShowStates": [
        "active tab blue underline",
        "warning badge with dot and label",
        "primary blue action",
        "mono numeric contrast ratios"
      ],
      "primitives": [
        "button",
        "card",
        "tabs",
        "badge",
        "separator",
        "table",
        "dropdown-menu",
        "tooltip"
      ],
      "scene": {
        "actions": [
          "Export tokens",
          "Approve batch"
        ],
        "description": "Approve accessible semantic token changes for a multi-product SaaS platform.",
        "eyebrow": "Semantic registry",
        "headline": "Palette governance queue",
        "rows": [
          {
            "contrast": "7.8:1",
            "status": "Blocked",
            "token": "status.error.soft"
          },
          {
            "contrast": "6.4:1",
            "status": "Active",
            "token": "focus.brand.ring"
          }
        ],
        "stats": [
          {
            "label": "AA coverage",
            "value": "98.4%"
          },
          {
            "label": "Blocked states",
            "value": "04"
          }
        ]
      }
    },
    {
      "avoid": [
        "raw hex field as primary workflow",
        "unlabeled color swatches"
      ],
      "composition": "Warm editor card with right evidence sheet and compact controls for role mapping.",
      "id": "detail-editor",
      "mustShowStates": [
        "blue focus ring",
        "3px warning rail",
        "switch with text label",
        "slider with mono value"
      ],
      "primitives": [
        "card",
        "input",
        "textarea",
        "select",
        "dialog",
        "sheet",
        "checkbox",
        "switch",
        "slider",
        "button",
        "badge"
      ],
      "scene": {
        "actions": [
          "Save alias",
          "Open contrast dialog"
        ],
        "description": "Review contrast notes, chart pattern requirements, and dark role parity before release.",
        "eyebrow": "Role editor",
        "fields": [
          {
            "label": "Alias path",
            "value": "semantic.status.warning.fg"
          },
          {
            "label": "Dark role",
            "value": "warning.300"
          }
        ],
        "headline": "Map warning foreground aliases",
        "stats": [
          {
            "label": "Contrast",
            "value": "5.4:1"
          }
        ]
      }
    },
    {
      "avoid": [
        "rainbow row accents",
        "low contrast tinted text"
      ],
      "composition": "Dense operations table with direct labels, chart-safe tokens, and neutral row actions.",
      "id": "data-operations",
      "mustShowStates": [
        "success error warning info badges",
        "tabular numerals",
        "neutral dropdown menu",
        "chart pattern note"
      ],
      "primitives": [
        "table",
        "badge",
        "separator",
        "button",
        "card",
        "tooltip",
        "dropdown-menu",
        "select"
      ],
      "scene": {
        "actions": [
          "Assign token",
          "Review policy"
        ],
        "description": "Assign colorblind-safe chart roles with pattern requirements and direct annotation.",
        "eyebrow": "Data operations",
        "headline": "Chart token assignment",
        "rows": [
          {
            "series": "Revenue forecast",
            "state": "Approved",
            "token": "chart.blue.600"
          },
          {
            "series": "Risk threshold",
            "state": "Needs label",
            "token": "chart.warning.pattern"
          },
          {
            "series": "Incident count",
            "state": "Blocked",
            "token": "status.error.fg"
          }
        ]
      }
    }
  ],
  "version": "preview-shots-v1",
  "visualProfile": {
    "accents": "trusted-blue semantic status ramps",
    "border": "one-pixel-plus-status-rail",
    "contour": "measured-radius",
    "density": "compact",
    "family": "enterprise-semantic",
    "grain": false,
    "material": "matte-neutral",
    "motion": "instant-operational",
    "stickerBadges": false,
    "underlay": "subtle-command-grid"
  }
}

More like this

Chromatic Decision Labshares semantic-color · saas Captioned Clarityshares semantic-color Gouache System Glassshares semantic-color Ledger Prism Editorial Shellshares neutral-foundation Quiet Grid Minimalismshares semantic-color Signal Porcelain Pixelshares semantic-color