back to gallery
design language·tonal-spectrum-console

Tonal Spectrum Console

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 UI design language for 2026 palette systems that turns harmonic color theory into semantic, accessible tonal roles. It treats hue as expressive but never as the only carrier of meaning, using blue-cyan-violet, amber-orange, chartreuse, and slate scales as measured product signals rather than decoration.
values
Semantic color roles remain stable across light, dark, and high-contrast modes even when raw hue shifts.Harmonic accent families are used proportionally: neutral surfaces dominate, blue-violet/cyan guides primary work, amber and chartreuse mark attention and completion.Every interactive color is paired with a tested foreground and a non-color affordance such as borders, icons, labels, or patterns.
anti-values
×Decorative rainbow interfaces where every panel competes for attention.×Red/green-only status systems that fail color-vision or high-contrast use cases.×Dark mode produced by simple inversion instead of deliberate tonal remapping.
tokens
borders4 items
accent width
3px
character
Borders are functional contrast instruments; selected and critical elements get double affordances through rail plus ring.
default width
1px
style
solid with dashed secondary separators for state rows
colors12 items
accent
#00A7C7
background
#F8FAFC
border
#CBD5E1
error
#B42318
info
#0369A1
muted
#64748B
primary
#2457D6
secondary
#6D3FE6
success
#3B7A10
surface
#FFFFFF
text
#0F172A
warning
#B45309
motion3 items
duration
160ms
easing
cubic-bezier(0.2, 0, 0, 1)
philosophy
Fast tonal confirmation: controls brighten, rails lengthen, and focus rings snap into place without playful bounce.
radii5 items
full
9999px
lg
18px
md
10px
none
0
sm
6px
shadows3 items
lg
0 30px 70px rgba(15, 23, 42, 0.18)
md
0 14px 36px rgba(15, 23, 42, 0.12)
sm
0 1px 2px rgba(15, 23, 42, 0.08)
spacing2 items
base
8px
scale
4, 8, 12, 16, 24, 32, 48, 64
surfaces3 items
bg pattern
Subtle OKLCH-inspired hue grid made from faint cyan and violet radial glows over a neutral slate field.
card style
Rounded rectangles with one clipped corner accent, 1px slate border, and a 3px semantic top rail when status is present.
treatment
Tonal slate surfaces with measured accent rails; light uses cool near-white containers, dark uses lifted slate panels with luminous outlines.
typography8 items
base size
16px
body font
Inter
google fonts url
https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@500;600;700&family=IBM+Plex+Mono:wght@500;600&family=Inter:wght@400;500;600;700&display=swap
heading font
IBM Plex Sans
letter spacing
-0.015em
line height
1.52
mono font
IBM Plex Mono
scale ratio
1.2
rules
composition
Compose screens as a 60-30-10 palette system: 60 percent slate-neutral workspace, 30 percent elevated containers, and 10 percent harmonic accent signals distributed by task priority.
density

Medium-dense operational layouts with compact controls, clear row rhythm, and generous gutters around analytic panels.

hierarchy
Use type weight, tonal contrast, rail thickness, and container elevation before adding more hue; accent color is reserved for interaction, state, and orientation.
signature patterns
Tonal role matrix cards show each semantic color as a vertical swatch stack with foreground chips and WCAG ratio labels.Complementary decision rails place blue-violet primary actions opposite amber warning/caution bands with icon and label redundancy.Adaptive mode toggles preview light, dark, and high-contrast mappings in three adjacent miniature surfaces.Status rows use patterned edge marks: solid for info, diagonal hatch for warning, dot grid for success, and double-line for error.
layout
breakpoints

Desktop 1200px+, tablet 720-1199px two-column stack, mobile below 720px single-column cards with horizontal token chips.

grid

Twelve-column desktop grid with a fixed left rail, broad central token matrix, and right-side accessibility inspector.

whitespace

Whitespace is measured and analytical: 24px panel gaps on desktop, 16px on tablet/mobile, dense 8px rhythm inside token controls.

guidance
do
  • Pair every accent background with a tested on-color foreground token and keep the semantic role name visible in copy or iconography.
  • Use neutral slate scales for large surfaces and reserve saturated hues for state, focus, and clear hierarchy.
  • Define separate light, dark, and high-contrast tonal mappings instead of algorithmic inversion.
  • Use patterns, borders, and icons in addition to hue for critical status states.
avoid
  • Do not rely on red/green alone to distinguish error from success.
  • Do not place saturated complementary colors in equal large areas; keep accent proportion near ten percent.
  • Do not use low-contrast cyan or amber text on light surfaces without a dark foreground pairing.
  • Do not let visual palette names replace semantic token names in product code.
katagami spec
# Tonal Spectrum Console

## Philosophy

A UI design language for 2026 palette systems that turns harmonic color theory into semantic, accessible tonal roles. It treats hue as expressive but never as the only carrier of meaning, using blue-cyan-violet, amber-orange, chartreuse, and slate scales as measured product signals rather than decoration.

### Values

- Semantic color roles remain stable across light, dark, and high-contrast modes even when raw hue shifts.
- Harmonic accent families are used proportionally: neutral surfaces dominate, blue-violet/cyan guides primary work, amber and chartreuse mark attention and completion.
- Every interactive color is paired with a tested foreground and a non-color affordance such as borders, icons, labels, or patterns.

### Anti-Values

- Decorative rainbow interfaces where every panel competes for attention.
- Red/green-only status systems that fail color-vision or high-contrast use cases.
- Dark mode produced by simple inversion instead of deliberate tonal remapping.

### Visual Character

- Use slate-neutral application chrome with layered panels that step from #F8FAFC to #E2E8F0 and dark counterparts from #0F172A to #1E293B.
- Place narrow cyan-to-violet tonal rails on primary navigation, selected rows, and focus zones while keeping large content fields neutral.
- Apply amber-orange callout bands and chartreuse success ticks as small semantic accents paired with text labels and icon geometry.
- Use contrast rings, dashed status separators, and patterned chips so warning, error, success, and information are readable without hue alone.

## Tokens

### Borders

- **Accent Width**: 3px
- **Character**: Borders are functional contrast instruments; selected and critical elements get double affordances through rail plus ring.
- **Default Width**: 1px
- **Style**: solid with dashed secondary separators for state rows

### Colors

| Name | Value |
|------|-------|
| accent | `#00A7C7` |
| background | `#F8FAFC` |
| border | `#CBD5E1` |
| error | `#B42318` |
| info | `#0369A1` |
| muted | `#64748B` |
| primary | `#2457D6` |
| secondary | `#6D3FE6` |
| success | `#3B7A10` |
| surface | `#FFFFFF` |
| text | `#0F172A` |
| warning | `#B45309` |

### Motion

- **Duration**: 160ms
- **Easing**: cubic-bezier(0.2, 0, 0, 1)
- **Philosophy**: Fast tonal confirmation: controls brighten, rails lengthen, and focus rings snap into place without playful bounce.

### Radii

- **Full**: 9999px
- **Lg**: 18px
- **Md**: 10px
- **None**: 0
- **Sm**: 6px

### Shadows

- **Lg**: 0 30px 70px rgba(15, 23, 42, 0.18)
- **Md**: 0 14px 36px rgba(15, 23, 42, 0.12)
- **Sm**: 0 1px 2px rgba(15, 23, 42, 0.08)

### Spacing

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

### Surfaces

- **Bg Pattern**: Subtle OKLCH-inspired hue grid made from faint cyan and violet radial glows over a neutral slate field.
- **Card Style**: Rounded rectangles with one clipped corner accent, 1px slate border, and a 3px semantic top rail when status is present.
- **Treatment**: Tonal slate surfaces with measured accent rails; light uses cool near-white containers, dark uses lifted slate panels with luminous outlines.

### Typography

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

## Rules

### Composition

Compose screens as a 60-30-10 palette system: 60 percent slate-neutral workspace, 30 percent elevated containers, and 10 percent harmonic accent signals distributed by task priority.

### Density

Medium-dense operational layouts with compact controls, clear row rhythm, and generous gutters around analytic panels.

### Hierarchy

Use type weight, tonal contrast, rail thickness, and container elevation before adding more hue; accent color is reserved for interaction, state, and orientation.

### Signature Patterns

- Tonal role matrix cards show each semantic color as a vertical swatch stack with foreground chips and WCAG ratio labels.
- Complementary decision rails place blue-violet primary actions opposite amber warning/caution bands with icon and label redundancy.
- Adaptive mode toggles preview light, dark, and high-contrast mappings in three adjacent miniature surfaces.
- Status rows use patterned edge marks: solid for info, diagonal hatch for warning, dot grid for success, and double-line for error.

## Layout

### Breakpoints

Desktop 1200px+, tablet 720-1199px two-column stack, mobile below 720px single-column cards with horizontal token chips.

### Grid

Twelve-column desktop grid with a fixed left rail, broad central token matrix, and right-side accessibility inspector.

### Whitespace

Whitespace is measured and analytical: 24px panel gaps on desktop, 16px on tablet/mobile, dense 8px rhythm inside token controls.

## Guidance

### Do

- Pair every accent background with a tested on-color foreground token and keep the semantic role name visible in copy or iconography.
- Use neutral slate scales for large surfaces and reserve saturated hues for state, focus, and clear hierarchy.
- Define separate light, dark, and high-contrast tonal mappings instead of algorithmic inversion.
- Use patterns, borders, and icons in addition to hue for critical status states.

### Don't

- Do not rely on red/green alone to distinguish error from success.
- Do not place saturated complementary colors in equal large areas; keep accent proportion near ten percent.
- Do not use low-contrast cyan or amber text on light surfaces without a dark foreground pairing.
- Do not let visual palette names replace semantic token names in product code.
DESIGN.md
---
version: "alpha"
name: "Tonal Spectrum Console"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  accent: "#00A7C7"
  background: "#F8FAFC"
  border: "#CBD5E1"
  error: "#B42318"
  info: "#0369A1"
  muted: "#64748B"
  primary: "#2457D6"
  secondary: "#6D3FE6"
  success: "#3B7A10"
  surface: "#FFFFFF"
  text: "#0F172A"
  warning: "#B45309"
typography:
  headline-lg:
    fontFamily: "IBM Plex Sans"
    fontSize: "1.728rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.015em"
  headline-md:
    fontFamily: "IBM Plex Sans"
    fontSize: "1.44rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.015em"
  body-md:
    fontFamily: "Inter"
    fontSize: "16px"
    fontWeight: 400
    lineHeight: 1.52
    letterSpacing: "-0.015em"
  label-md:
    fontFamily: "IBM Plex Mono"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
rounded:
  full: "9999px"
  lg: "18px"
  md: "10px"
  none: "0px"
  sm: "6px"
spacing:
  base: "8px"
  xs: "4px"
  sm: "8px"
  md: "12px"
  lg: "16px"
  xl: "24px"
  2xl: "32px"
  3xl: "48px"
  4xl: "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"
---

# Tonal Spectrum Console

## Overview

A UI design language for 2026 palette systems that turns harmonic color theory into semantic, accessible tonal roles. It treats hue as expressive but never as the only carrier of meaning, using blue-cyan-violet, amber-orange, chartreuse, and slate scales as measured product signals rather than decoration.

### Values

- Semantic color roles remain stable across light, dark, and high-contrast modes even when raw hue shifts.
- Harmonic accent families are used proportionally: neutral surfaces dominate, blue-violet/cyan guides primary work, amber and chartreuse mark attention and completion.
- Every interactive color is paired with a tested foreground and a non-color affordance such as borders, icons, labels, or patterns.

### Anti-Values

- Decorative rainbow interfaces where every panel competes for attention.
- Red/green-only status systems that fail color-vision or high-contrast use cases.
- Dark mode produced by simple inversion instead of deliberate tonal remapping.

### Visual Character

- Use slate-neutral application chrome with layered panels that step from #F8FAFC to #E2E8F0 and dark counterparts from #0F172A to #1E293B.
- Place narrow cyan-to-violet tonal rails on primary navigation, selected rows, and focus zones while keeping large content fields neutral.
- Apply amber-orange callout bands and chartreuse success ticks as small semantic accents paired with text labels and icon geometry.
- Use contrast rings, dashed status separators, and patterned chips so warning, error, success, and information are readable without hue alone.

## 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 | `#00A7C7` |
| background | `#F8FAFC` |
| border | `#CBD5E1` |
| error | `#B42318` |
| info | `#0369A1` |
| muted | `#64748B` |
| primary | `#2457D6` |
| secondary | `#6D3FE6` |
| success | `#3B7A10` |
| surface | `#FFFFFF` |
| text | `#0F172A` |
| warning | `#B45309` |

## Typography

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

## Layout

### Spacing Tokens

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

### Breakpoints

Desktop 1200px+, tablet 720-1199px two-column stack, mobile below 720px single-column cards with horizontal token chips.

### Grid

Twelve-column desktop grid with a fixed left rail, broad central token matrix, and right-side accessibility inspector.

### Whitespace

Whitespace is measured and analytical: 24px panel gaps on desktop, 16px on tablet/mobile, dense 8px rhythm inside token controls.

## Elevation & Depth

### Shadows

- **Lg**: 0 30px 70px rgba(15, 23, 42, 0.18)
- **Md**: 0 14px 36px rgba(15, 23, 42, 0.12)
- **Sm**: 0 1px 2px rgba(15, 23, 42, 0.08)

## Shapes

### Rounded

- **Full**: `9999px`
- **Lg**: `18px`
- **Md**: `10px`
- **None**: `0px`
- **Sm**: `6px`

### Surfaces

- **Bg Pattern**: Subtle OKLCH-inspired hue grid made from faint cyan and violet radial glows over a neutral slate field.
- **Card Style**: Rounded rectangles with one clipped corner accent, 1px slate border, and a 3px semantic top rail when status is present.
- **Treatment**: Tonal slate surfaces with measured accent rails; light uses cool near-white containers, dark uses lifted slate panels with luminous outlines.

### Borders

- **Accent Width**: 3px
- **Character**: Borders are functional contrast instruments; selected and critical elements get double affordances through rail plus ring.
- **Default Width**: 1px
- **Style**: solid with dashed secondary separators for state rows

## Components

### Composition

Compose screens as a 60-30-10 palette system: 60 percent slate-neutral workspace, 30 percent elevated containers, and 10 percent harmonic accent signals distributed by task priority.

### Density

Medium-dense operational layouts with compact controls, clear row rhythm, and generous gutters around analytic panels.

### Hierarchy

Use type weight, tonal contrast, rail thickness, and container elevation before adding more hue; accent color is reserved for interaction, state, and orientation.

### Signature Patterns

- Tonal role matrix cards show each semantic color as a vertical swatch stack with foreground chips and WCAG ratio labels.
- Complementary decision rails place blue-violet primary actions opposite amber warning/caution bands with icon and label redundancy.
- Adaptive mode toggles preview light, dark, and high-contrast mappings in three adjacent miniature surfaces.
- Status rows use patterned edge marks: solid for info, diagonal hatch for warning, dot grid for success, and double-line for error.

## 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-019ea9a2-5b8b-7ac0-8d7d-211ea9d4e633/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 Pair every accent background with a tested on-color foreground token and keep the semantic role name visible in copy or iconography.
- Do Use neutral slate scales for large surfaces and reserve saturated hues for state, focus, and clear hierarchy.
- Do Define separate light, dark, and high-contrast tonal mappings instead of algorithmic inversion.
- Do Use patterns, borders, and icons in addition to hue for critical status states.
- Don't Do not rely on red/green alone to distinguish error from success.
- Don't Do not place saturated complementary colors in equal large areas; keep accent proportion near ten percent.
- Don't Do not use low-contrast cyan or amber text on light surfaces without a dark foreground pairing.
- Don't Do not let visual palette names replace semantic token names in product code.
shadcn/ui theme
```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "tonal-spectrum-console",
  "type": "registry:theme",
  "title": "Tonal Spectrum Console shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F8FAFC",
      "foreground": "#0F172A",
      "card": "#FFFFFF",
      "card-foreground": "#0F172A",
      "popover": "#FFFFFF",
      "popover-foreground": "#0F172A",
      "primary": "#2457D6",
      "primary-foreground": "#ffffff",
      "secondary": "#6D3FE6",
      "secondary-foreground": "#ffffff",
      "muted": "#64748B",
      "muted-foreground": "#0F172A",
      "accent": "#00A7C7",
      "accent-foreground": "#ffffff",
      "destructive": "#B42318",
      "border": "#CBD5E1",
      "input": "#CBD5E1",
      "ring": "#00A7C7",
      "chart-1": "#2457D6",
      "chart-2": "#6D3FE6",
      "chart-3": "#00A7C7",
      "chart-4": "#3B7A10",
      "chart-5": "#B45309",
      "sidebar": "#FFFFFF",
      "sidebar-foreground": "#0F172A",
      "sidebar-primary": "#2457D6",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#0369A1",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#CBD5E1",
      "sidebar-ring": "#00A7C7",
      "radius": "10px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#2457D6",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#00A7C7",
      "accent-foreground": "#ffffff",
      "destructive": "#B42318",
      "border": "#303642",
      "input": "#303642",
      "ring": "#00A7C7",
      "chart-1": "#2457D6",
      "chart-2": "#6D3FE6",
      "chart-3": "#00A7C7",
      "chart-4": "#3B7A10",
      "chart-5": "#B45309",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#2457D6",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#00A7C7",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#00A7C7",
      "radius": "10px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019ea9a2-5b8b-7ac0-8d7d-211ea9d4e633",
    "slug": "tonal-spectrum-console",
    "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 · tonal-spectrum-console
DESIGN.md

at a glance

Palette

Typography

headline-lgIBM Plex Sans · 28px · 700

The quick brown fox jumps

headline-mdIBM Plex 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
  • xl24px
  • 2xl32px
  • 3xl48px
  • 4xl64px

Shape

full9999px
lg18px
md10px
none0px
sm6px
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
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: #F8FAFC;
  --foreground: #0F172A;
  --card: #FFFFFF;
  --card-foreground: #0F172A;
  --popover: #FFFFFF;
  --popover-foreground: #0F172A;
  --primary: #2457D6;
  --primary-foreground: #ffffff;
  --secondary: #6D3FE6;
  --secondary-foreground: #ffffff;
  --muted: #64748B;
  --muted-foreground: #0F172A;
  --accent: #00A7C7;
  --accent-foreground: #ffffff;
  --destructive: #B42318;
  --border: #CBD5E1;
  --input: #CBD5E1;
  --ring: #00A7C7;
  --chart-1: #2457D6;
  --chart-2: #6D3FE6;
  --chart-3: #00A7C7;
  --chart-4: #3B7A10;
  --chart-5: #B45309;
  --sidebar: #FFFFFF;
  --sidebar-foreground: #0F172A;
  --sidebar-primary: #2457D6;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #0369A1;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #CBD5E1;
  --sidebar-ring: #00A7C7;
  --radius: 10px;
}

.dark {
  --background: #0f1115;
  --foreground: #f8fafc;
  --card: #181b22;
  --card-foreground: #f8fafc;
  --popover: #181b22;
  --popover-foreground: #f8fafc;
  --primary: #2457D6;
  --primary-foreground: #ffffff;
  --secondary: #252a33;
  --secondary-foreground: #f8fafc;
  --muted: #252a33;
  --muted-foreground: #a1a1aa;
  --accent: #00A7C7;
  --accent-foreground: #ffffff;
  --destructive: #B42318;
  --border: #303642;
  --input: #303642;
  --ring: #00A7C7;
  --chart-1: #2457D6;
  --chart-2: #6D3FE6;
  --chart-3: #00A7C7;
  --chart-4: #3B7A10;
  --chart-5: #B45309;
  --sidebar: #181b22;
  --sidebar-foreground: #f8fafc;
  --sidebar-primary: #2457D6;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #00A7C7;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #303642;
  --sidebar-ring: #00A7C7;
  --radius: 10px;
}
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 TonalSpectrumConsoleShadcnKit() {
  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">Tonal Spectrum Console</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": "tonal-spectrum-console",
  "type": "registry:theme",
  "title": "Tonal Spectrum Console shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F8FAFC",
      "foreground": "#0F172A",
      "card": "#FFFFFF",
      "card-foreground": "#0F172A",
      "popover": "#FFFFFF",
      "popover-foreground": "#0F172A",
      "primary": "#2457D6",
      "primary-foreground": "#ffffff",
      "secondary": "#6D3FE6",
      "secondary-foreground": "#ffffff",
      "muted": "#64748B",
      "muted-foreground": "#0F172A",
      "accent": "#00A7C7",
      "accent-foreground": "#ffffff",
      "destructive": "#B42318",
      "border": "#CBD5E1",
      "input": "#CBD5E1",
      "ring": "#00A7C7",
      "chart-1": "#2457D6",
      "chart-2": "#6D3FE6",
      "chart-3": "#00A7C7",
      "chart-4": "#3B7A10",
      "chart-5": "#B45309",
      "sidebar": "#FFFFFF",
      "sidebar-foreground": "#0F172A",
      "sidebar-primary": "#2457D6",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#0369A1",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#CBD5E1",
      "sidebar-ring": "#00A7C7",
      "radius": "10px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#2457D6",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#00A7C7",
      "accent-foreground": "#ffffff",
      "destructive": "#B42318",
      "border": "#303642",
      "input": "#303642",
      "ring": "#00A7C7",
      "chart-1": "#2457D6",
      "chart-2": "#6D3FE6",
      "chart-3": "#00A7C7",
      "chart-4": "#3B7A10",
      "chart-5": "#B45309",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#2457D6",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#00A7C7",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#00A7C7",
      "radius": "10px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019ea9a2-5b8b-7ac0-8d7d-211ea9d4e633",
    "slug": "tonal-spectrum-console",
    "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
# Tonal Spectrum Console shadcn/ui Components
Author: `katagami-agent`

## Intent
Bring accessible harmonic palette work into shadcn/ui application screens. Preserve semantic token names, tonal contrast, rail-based orientation, and non-color status affordances.

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

## Token cues
Use primary blue for committed actions, cyan for focus and info, violet for secondary navigation, amber for warning, deep red for error, and chartreuse-green only with labels/patterns for success. Large surfaces remain slate/white.

## Visual character to preserve
Slate-neutral surfaces; cyan-violet rails; amber/chartreuse semantic accents; dashed separators and patterned status edges; clipped-corner analytical cards.

## ShadSync visual profile
family: tonal-accessible; material: slate-panels; contour: clipped-rounded; border: contrast-rail; underlay: subtle-grid; grain: false; stickerBadges: false; motion: snap-confirm; density: medium-dense; accents: blue, cyan, violet, amber, chartreuse.

## Signature component recipes
- button: rounded-full, bold label, primary blue fill with white foreground; secondary buttons are white with slate border; focus ring is cyan and visible.
- card: rounded-lg with 1px slate border, optional 3px top rail, and one clipped corner via pseudo-element or wrapper mask.
- input: slate-50 background, slate border, cyan focus ring, visible label and helper text.
- textarea: same as input with mono token snippets for export fields.
- select: compact field with chevron, cyan focus ring, and semantic role labels.
- dialog: elevated slate/white panel with top tonal rail and contrast checklist content.
- sheet: right-side inspector with row rhythm and dashed separators.
- tabs: role-mode tabs for light, dark, high-contrast; active tab gets blue rail plus text label.
- badge: pill with dot/icon plus text; never color-only.
- separator: dashed for status groups, solid for structural divisions.
- checkbox: square with cyan focus and explicit adjacent label.
- switch: mode toggles use text labels and not color alone.
- slider: tonal value scale for chroma/tone with numeric output.
- tooltip: dark slate surface with white text and token name.
- dropdown-menu: compact menu with active rail and semantic action grouping.
- table: dense token rows with swatch, foreground, ratio, and mode columns.

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

## Implementation contract
Import local primitives from `@/components/ui/*`. Do not invent a second component system. Map raw hues through semantic CSS variables and keep on-color foregrounds explicit.

## 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 TonalTokenCard() {
  return (
    <Card className="overflow-hidden rounded-[18px] border-slate-300 shadow-sm before:block before:h-[3px] before:bg-gradient-to-r before:from-blue-700 before:via-cyan-500 before:to-violet-700">
      <CardHeader>
        <Badge className="w-fit rounded-full bg-slate-50 text-slate-900 border border-slate-300">AA checked</Badge>
        <CardTitle className="font-semibold tracking-tight">Primary / on-primary</CardTitle>
      </CardHeader>
      <CardContent className="space-y-3">
        <Input value="#2457D6 / #FFFFFF" readOnly className="focus-visible:ring-cyan-500" />
        <Table><TableHeader><TableRow><TableHead>Mode</TableHead><TableHead>Ratio</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Light</TableCell><TableCell>8.1:1</TableCell></TableRow></TableBody></Table>
        <Button className="rounded-full bg-blue-700 text-white focus-visible:ring-cyan-500">Export tokens</Button>
      </CardContent>
    </Card>
  )
}
```
preview shotsstored
{
  "artifact": "katagami:shadcn-preview-shots",
  "author": "katagami-agent",
  "componentRecipes": [
    {
      "primitive": "button",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "card",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "input",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "textarea",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "select",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "dialog",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "sheet",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "tabs",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "badge",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "separator",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "checkbox",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "switch",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "slider",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "tooltip",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "dropdown-menu",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    },
    {
      "primitive": "table",
      "recipe": "Use Tonal Spectrum Console semantic tokens, slate borders, cyan focus rings, explicit labels, and rail/pattern affordances."
    }
  ],
  "generatedBy": "katagami-agent",
  "renderable": true,
  "requiresVisualProfile": true,
  "schema": "katagami:shadcn-preview-shots/renderable-v1",
  "shots": [
    {
      "avoid": [
        "generic rainbow wall",
        "color-only statuses"
      ],
      "composition": "Left navigation, central semantic role matrix, and right contrast inspector with tonal rails.",
      "id": "application-shell",
      "mustShowStates": [
        "active navigation rail",
        "AA badge",
        "light/dark/high-contrast switch",
        "warning hatch row"
      ],
      "primitives": [
        "button",
        "card",
        "tabs",
        "badge",
        "separator",
        "table",
        "tooltip",
        "dropdown-menu",
        "switch"
      ],
      "scene": {
        "actions": [
          "Generate token map",
          "Run WCAG audit"
        ],
        "description": "Audit primary, secondary, warning, success, error, and neutral roles before export.",
        "eyebrow": "Palette operations",
        "headline": "Semantic role matrix",
        "rows": [
          {
            "hex": "#2457D6",
            "on": "#FFFFFF",
            "ratio": "8.1:1",
            "role": "primary"
          },
          {
            "hex": "#B45309",
            "on": "#FFFFFF",
            "ratio": "5.4:1",
            "role": "warning"
          }
        ],
        "stats": [
          {
            "label": "Pairs checked",
            "value": "48"
          },
          {
            "label": "AA pass",
            "value": "46"
          },
          {
            "label": "Modes",
            "value": "3"
          }
        ]
      }
    },
    {
      "avoid": [
        "unlabeled swatches",
        "disabled-looking contrast text"
      ],
      "composition": "Token detail dialog with chroma/tone sliders, foreground field, and accessibility checklist.",
      "id": "detail-editor",
      "mustShowStates": [
        "cyan focus ring",
        "numeric tone output",
        "checked contrast item",
        "error text with icon"
      ],
      "primitives": [
        "dialog",
        "input",
        "slider",
        "checkbox",
        "badge",
        "button",
        "tooltip"
      ],
      "scene": {
        "actions": [
          "Save role",
          "Compare modes"
        ],
        "description": "Tune color values while preserving semantic naming and non-color status cues.",
        "eyebrow": "Role editor",
        "headline": "Primary tone adjustment",
        "rows": [
          {
            "hex": "#FFFFFF",
            "on": "#2457D6",
            "ratio": "8.1:1",
            "role": "foreground"
          }
        ],
        "stats": [
          {
            "label": "Tone",
            "value": "54"
          },
          {
            "label": "Chroma",
            "value": "62"
          }
        ]
      }
    },
    {
      "avoid": [
        "raw hue names replacing semantic names",
        "floating ungrouped controls"
      ],
      "composition": "Right sheet with export options, dense token table, and dashed separators between semantic groups.",
      "id": "data-operations",
      "mustShowStates": [
        "export format select",
        "patterned success badge",
        "dashed semantic separator",
        "token code textarea"
      ],
      "primitives": [
        "sheet",
        "select",
        "textarea",
        "table",
        "separator",
        "badge",
        "button",
        "switch"
      ],
      "scene": {
        "actions": [
          "Copy CSS variables",
          "Download JSON"
        ],
        "description": "Package CSS variables, JSON tokens, and shadcn theme mappings with review metadata.",
        "eyebrow": "Export queue",
        "headline": "Semantic tokens ready for handoff",
        "rows": [
          {
            "hex": "#00A7C7",
            "on": "#0F172A",
            "ratio": "6.2:1",
            "role": "accent"
          }
        ],
        "stats": [
          {
            "label": "Exports",
            "value": "3"
          },
          {
            "label": "Warnings",
            "value": "2"
          }
        ]
      }
    }
  ],
  "version": "preview-shots-v1",
  "visualProfile": {
    "accents": [
      "blue",
      "cyan",
      "violet",
      "amber",
      "chartreuse"
    ],
    "border": "contrast-rail",
    "contour": "clipped-rounded",
    "density": "medium-dense",
    "family": "tonal-accessible",
    "material": "slate-panels",
    "motion": "snap-confirm",
    "underlay": "subtle-grid"
  }
}