design language·surreal-sensory-gradient-system

Surreal Sensory Gradient System

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

A production-credible color language for creative interfaces where immersive mesh and lumen gradients act as controlled scenic layers while plain semantic UI tokens keep product workflows legible, accessible, and enterprise-ready.

values

sensory immersion with restraintsemantic token clarity before spectaclewide-gamut readiness with solid fallbackswarm/cool chroma balanceaccessibility at the worst contrast point

anti-values

×generic AI rainbow blobs or unconstrained aurora fields×gradient hues used as categorical chart defaults×text placed directly on untested decorative gradients×brand color novelty that overrides status semantics

tokens

borders4 items

accent width: 2px
character: soft technical frames that separate operational UI from atmospheric brand light
default width: 1px
style: solid with optional masked gradient border on hero/editor containers

colors12 items

accent

#FF6BAA

background

#F8F6F1

border

#DCD6E6

error

#C7374F

info

#246BFE

muted

#706A7A

primary

#6047FF

secondary

#00A6C8

success

#177B55

surface

#FFFFFF

text

#17151F

warning

#B97800

gradient_primitives7 items

default opacity: 0.34
fallback solids: brand #6047FF·cool #D8F4F6·warm #FCE2D3
iridescent edge: #F5F0FF, #A9F4FF, #FFB8D6, #6E5BFF
lumen cool: #00D1B2, #00A6C8, #6047FF
lumen warm: #FFB86B, #FF6BAA, #6047FF
max stops: 4
text rule: decorative only unless contrast is tested at darkest and lightest sampled point

motion3 items

duration: 180ms
easing: cubic-bezier(.2,.8,.2,1)
philosophy: short luminance shifts and edge-glow reveals; no drifting blobs during reading or data tasks

radii5 items

full: 9999px
lg: 28px
md: 16px
none: 0
sm: 10px

shadows3 items

lg: 0 32px 90px rgba(70,54,150,0.22)
md: 0 18px 45px rgba(55,42,110,0.14)
sm: 0 1px 2px rgba(23,21,31,0.08)

spacing2 items

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

surfaces3 items

bg pattern: large blurred mesh halos anchored to corners, never repeated rainbow wallpaper
card style: white or blue-black cards with quiet borders and one controlled iridescent edge or corner glow
treatment: plain warm-neutral application surfaces with translucent gradient underlays isolated behind content

typography8 items

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

rules

composition

Use a plain product shell first: neutral navigation, semantic panels, and data grids sit above one or two oversized gradient underlays that frame immersive moments without reducing legibility.

density

Balanced creative-tool density with generous canvas whitespace, compact metadata rows, and high-information tables that never depend on decorative gradient color.

hierarchy

Reserve strongest chroma for hero canvas previews, active selection, and primary creative actions; secondary controls use ink, neutral surfaces, and restrained blue or violet accents.

signature patterns

Masked lumen mesh underlays sit behind hero or preview canvases using radial gradients clipped by soft oval masks and capped at four stops.Iridescent hairline borders use a conic-gradient border layer around editor cards while the card interior stays solid and contrast-safe.Semantic UI tokens map status, focus, and data states to stable solids while gradient primitives are named separately as brand or atmosphere primitives.Chroma discipline pairs one warm coral-pink transition with one cool cyan-violet transition per view, preventing rainbow accumulation.

layout

breakpoints

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

grid

Twelve-column desktop shell with fixed utility rail, wide canvas column, and narrow inspector column; collapses to two columns on tablet and a single stacked flow on mobile.

whitespace

Use 24px to 48px breathing room around immersive canvases and 12px to 16px rhythm for operational form and table controls.

guidance

Separate gradient primitives from semantic UI tokens and document stops, opacity, and fallback solids.
Use plain neutral cards for forms, tables, and navigation so expressive canvases feel intentional.
Limit each moment to two gradient families and four stops, with warm/cool balance checked in light and dark themes.
Provide colorblind-safe data visualization palettes independent from brand gradients.

avoid

Do not use gradient hues as categorical chart defaults or status colors.
Do not place body text or small labels directly on mesh gradients without a tested solid scrim.
Do not create generic AI rainbow blobs, excessive stop counts, or constantly animated auroras.
Do not let dark mode simply invert; tune luminance and opacity for calm blue-black surfaces.

katagami spec

# Surreal Sensory Gradient System

## Philosophy

A production-credible color language for creative interfaces where immersive mesh and lumen gradients act as controlled scenic layers while plain semantic UI tokens keep product workflows legible, accessible, and enterprise-ready.

### Values

- sensory immersion with restraint
- semantic token clarity before spectacle
- wide-gamut readiness with solid fallbacks
- warm/cool chroma balance
- accessibility at the worst contrast point

### Anti-Values

- generic AI rainbow blobs or unconstrained aurora fields
- gradient hues used as categorical chart defaults
- text placed directly on untested decorative gradients
- brand color novelty that overrides status semantics

### Visual Character

- Decorative gradient canvases are confined to large underlay halos, card edge glows, and hero lenses using two to four OKLCH-planned color stops with opacity masks.
- Core application surfaces remain plain warm-neutral and ink tokens, with gradients separated into primitive variables instead of semantic background or text colors.
- Iridescent transition bands appear as thin borders, focus rings, progress rails, and preview frames rather than filling every control.
- Dark mode inverts luminance through deep aubergine and blue-black solids while preserving the same gradient stop families at lower opacity.

## Tokens

### Borders

- **Accent Width**: 2px
- **Character**: soft technical frames that separate operational UI from atmospheric brand light
- **Default Width**: 1px
- **Style**: solid with optional masked gradient border on hero/editor containers

### Colors

| Name | Value |
|------|-------|
| accent | `#FF6BAA` |
| background | `#F8F6F1` |
| border | `#DCD6E6` |
| error | `#C7374F` |
| info | `#246BFE` |
| muted | `#706A7A` |
| primary | `#6047FF` |
| secondary | `#00A6C8` |
| success | `#177B55` |
| surface | `#FFFFFF` |
| text | `#17151F` |
| warning | `#B97800` |

### Gradient Primitives

- **Default Opacity**: 0.34
- **Fallback Solids**: {"brand":"#6047FF","cool":"#D8F4F6","warm":"#FCE2D3"}
- **Iridescent Edge**: ["#F5F0FF","#A9F4FF","#FFB8D6","#6E5BFF"]
- **Lumen Cool**: ["#00D1B2","#00A6C8","#6047FF"]
- **Lumen Warm**: ["#FFB86B","#FF6BAA","#6047FF"]
- **Max Stops**: 4
- **Text Rule**: decorative only unless contrast is tested at darkest and lightest sampled point

### Motion

- **Duration**: 180ms
- **Easing**: cubic-bezier(.2,.8,.2,1)
- **Philosophy**: short luminance shifts and edge-glow reveals; no drifting blobs during reading or data tasks

### Radii

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

### Shadows

- **Lg**: 0 32px 90px rgba(70,54,150,0.22)
- **Md**: 0 18px 45px rgba(55,42,110,0.14)
- **Sm**: 0 1px 2px rgba(23,21,31,0.08)

### Spacing

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

### Surfaces

- **Bg Pattern**: large blurred mesh halos anchored to corners, never repeated rainbow wallpaper
- **Card Style**: white or blue-black cards with quiet borders and one controlled iridescent edge or corner glow
- **Treatment**: plain warm-neutral application surfaces with translucent gradient underlays isolated behind content

### Typography

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

## Rules

### Composition

Use a plain product shell first: neutral navigation, semantic panels, and data grids sit above one or two oversized gradient underlays that frame immersive moments without reducing legibility.

### Density

Balanced creative-tool density with generous canvas whitespace, compact metadata rows, and high-information tables that never depend on decorative gradient color.

### Hierarchy

Reserve strongest chroma for hero canvas previews, active selection, and primary creative actions; secondary controls use ink, neutral surfaces, and restrained blue or violet accents.

### Signature Patterns

- Masked lumen mesh underlays sit behind hero or preview canvases using radial gradients clipped by soft oval masks and capped at four stops.
- Iridescent hairline borders use a conic-gradient border layer around editor cards while the card interior stays solid and contrast-safe.
- Semantic UI tokens map status, focus, and data states to stable solids while gradient primitives are named separately as brand or atmosphere primitives.
- Chroma discipline pairs one warm coral-pink transition with one cool cyan-violet transition per view, preventing rainbow accumulation.

## Layout

### Breakpoints

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

### Grid

Twelve-column desktop shell with fixed utility rail, wide canvas column, and narrow inspector column; collapses to two columns on tablet and a single stacked flow on mobile.

### Whitespace

Use 24px to 48px breathing room around immersive canvases and 12px to 16px rhythm for operational form and table controls.

## Guidance

### Do

- Separate gradient primitives from semantic UI tokens and document stops, opacity, and fallback solids.
- Use plain neutral cards for forms, tables, and navigation so expressive canvases feel intentional.
- Limit each moment to two gradient families and four stops, with warm/cool balance checked in light and dark themes.
- Provide colorblind-safe data visualization palettes independent from brand gradients.

### Don't

- Do not use gradient hues as categorical chart defaults or status colors.
- Do not place body text or small labels directly on mesh gradients without a tested solid scrim.
- Do not create generic AI rainbow blobs, excessive stop counts, or constantly animated auroras.
- Do not let dark mode simply invert; tune luminance and opacity for calm blue-black surfaces.

### Accessibility

All text, icons, focus states, and status indicators use semantic solids that meet WCAG 2.2 AA; decorative gradients require sampled worst-point contrast before supporting text.

DESIGN.md

---
version: "alpha"
name: "Surreal Sensory Gradient System"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  accent: "#FF6BAA"
  background: "#F8F6F1"
  border: "#DCD6E6"
  error: "#C7374F"
  info: "#246BFE"
  muted: "#706A7A"
  primary: "#6047FF"
  secondary: "#00A6C8"
  success: "#177B55"
  surface: "#FFFFFF"
  text: "#17151F"
  warning: "#B97800"
typography:
  headline-lg:
    fontFamily: "Space Grotesk"
    fontSize: "1.816rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.015em"
  headline-md:
    fontFamily: "Space Grotesk"
    fontSize: "1.488rem"
    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: "28px"
  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"
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"
---

# Surreal Sensory Gradient System

## Overview

A production-credible color language for creative interfaces where immersive mesh and lumen gradients act as controlled scenic layers while plain semantic UI tokens keep product workflows legible, accessible, and enterprise-ready.

### Values

- sensory immersion with restraint
- semantic token clarity before spectacle
- wide-gamut readiness with solid fallbacks
- warm/cool chroma balance
- accessibility at the worst contrast point

### Anti-Values

- generic AI rainbow blobs or unconstrained aurora fields
- gradient hues used as categorical chart defaults
- text placed directly on untested decorative gradients
- brand color novelty that overrides status semantics

### Visual Character

- Decorative gradient canvases are confined to large underlay halos, card edge glows, and hero lenses using two to four OKLCH-planned color stops with opacity masks.
- Core application surfaces remain plain warm-neutral and ink tokens, with gradients separated into primitive variables instead of semantic background or text colors.
- Iridescent transition bands appear as thin borders, focus rings, progress rails, and preview frames rather than filling every control.
- Dark mode inverts luminance through deep aubergine and blue-black solids while preserving the same gradient stop families at lower opacity.

## 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 | `#FF6BAA` |
| background | `#F8F6F1` |
| border | `#DCD6E6` |
| error | `#C7374F` |
| info | `#246BFE` |
| muted | `#706A7A` |
| primary | `#6047FF` |
| secondary | `#00A6C8` |
| success | `#177B55` |
| surface | `#FFFFFF` |
| text | `#17151F` |
| warning | `#B97800` |

## Typography

- **Headline-Lg**: Space Grotesk, 1.816rem, weight 700, line-height 1.1.
- **Headline-Md**: Space Grotesk, 1.488rem, 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

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

### Grid

Twelve-column desktop shell with fixed utility rail, wide canvas column, and narrow inspector column; collapses to two columns on tablet and a single stacked flow on mobile.

### Whitespace

Use 24px to 48px breathing room around immersive canvases and 12px to 16px rhythm for operational form and table controls.

## Elevation & Depth

### Shadows

- **Lg**: 0 32px 90px rgba(70,54,150,0.22)
- **Md**: 0 18px 45px rgba(55,42,110,0.14)
- **Sm**: 0 1px 2px rgba(23,21,31,0.08)

## Shapes

### Rounded

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

### Surfaces

- **Bg Pattern**: large blurred mesh halos anchored to corners, never repeated rainbow wallpaper
- **Card Style**: white or blue-black cards with quiet borders and one controlled iridescent edge or corner glow
- **Treatment**: plain warm-neutral application surfaces with translucent gradient underlays isolated behind content

### Borders

- **Accent Width**: 2px
- **Character**: soft technical frames that separate operational UI from atmospheric brand light
- **Default Width**: 1px
- **Style**: solid with optional masked gradient border on hero/editor containers

## Components

### Composition

Use a plain product shell first: neutral navigation, semantic panels, and data grids sit above one or two oversized gradient underlays that frame immersive moments without reducing legibility.

### Density

Balanced creative-tool density with generous canvas whitespace, compact metadata rows, and high-information tables that never depend on decorative gradient color.

### Hierarchy

Reserve strongest chroma for hero canvas previews, active selection, and primary creative actions; secondary controls use ink, neutral surfaces, and restrained blue or violet accents.

### Signature Patterns

- Masked lumen mesh underlays sit behind hero or preview canvases using radial gradients clipped by soft oval masks and capped at four stops.
- Iridescent hairline borders use a conic-gradient border layer around editor cards while the card interior stays solid and contrast-safe.
- Semantic UI tokens map status, focus, and data states to stable solids while gradient primitives are named separately as brand or atmosphere primitives.
- Chroma discipline pairs one warm coral-pink transition with one cool cyan-violet transition per view, preventing rainbow accumulation.

## 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-019ea9b5-bc1b-7ee1-8298-6e3c77a60c80/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 Separate gradient primitives from semantic UI tokens and document stops, opacity, and fallback solids.
- Do Use plain neutral cards for forms, tables, and navigation so expressive canvases feel intentional.
- Do Limit each moment to two gradient families and four stops, with warm/cool balance checked in light and dark themes.
- Do Provide colorblind-safe data visualization palettes independent from brand gradients.
- Don't Do not use gradient hues as categorical chart defaults or status colors.
- Don't Do not place body text or small labels directly on mesh gradients without a tested solid scrim.
- Don't Do not create generic AI rainbow blobs, excessive stop counts, or constantly animated auroras.
- Don't Do not let dark mode simply invert; tune luminance and opacity for calm blue-black surfaces.

### Accessibility

All text, icons, focus states, and status indicators use semantic solids that meet WCAG 2.2 AA; decorative gradients require sampled worst-point contrast before supporting text.

shadcn/ui theme

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "surreal-sensory-gradient-system",
  "type": "registry:theme",
  "title": "Surreal Sensory Gradient System shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F8F6F1",
      "foreground": "#17151F",
      "card": "#FFFFFF",
      "card-foreground": "#17151F",
      "popover": "#FFFFFF",
      "popover-foreground": "#17151F",
      "primary": "#6047FF",
      "primary-foreground": "#ffffff",
      "secondary": "#00A6C8",
      "secondary-foreground": "#ffffff",
      "muted": "#706A7A",
      "muted-foreground": "#17151F",
      "accent": "#FF6BAA",
      "accent-foreground": "#ffffff",
      "destructive": "#C7374F",
      "border": "#DCD6E6",
      "input": "#DCD6E6",
      "ring": "#FF6BAA",
      "chart-1": "#6047FF",
      "chart-2": "#00A6C8",
      "chart-3": "#FF6BAA",
      "chart-4": "#177B55",
      "chart-5": "#B97800",
      "sidebar": "#FFFFFF",
      "sidebar-foreground": "#17151F",
      "sidebar-primary": "#6047FF",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#246BFE",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#DCD6E6",
      "sidebar-ring": "#FF6BAA",
      "radius": "16px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#6047FF",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#FF6BAA",
      "accent-foreground": "#ffffff",
      "destructive": "#C7374F",
      "border": "#303642",
      "input": "#303642",
      "ring": "#FF6BAA",
      "chart-1": "#6047FF",
      "chart-2": "#00A6C8",
      "chart-3": "#FF6BAA",
      "chart-4": "#177B55",
      "chart-5": "#B97800",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#6047FF",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#FF6BAA",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#FF6BAA",
      "radius": "16px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019ea9b5-bc1b-7ee1-8298-6e3c77a60c80",
    "slug": "surreal-sensory-gradient-system",
    "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"
      ],
      "gradient_primitives": [
        "default_opacity",
        "fallback_solids",
        "iridescent_edge",
        "lumen_cool",
        "lumen_warm",
        "max_stops",
        "text_rule"
      ],
      "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 · surreal-sensory-gradient-system

DESIGN.md

at a glance

Palette

Typography

headline-lgSpace Grotesk · 29px · 700

The quick brown fox jumps

headline-mdSpace Grotesk · 24px · 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

lg28px

md16px

none0px

sm10px

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: #F8F6F1;
  --foreground: #17151F;
  --card: #FFFFFF;
  --card-foreground: #17151F;
  --popover: #FFFFFF;
  --popover-foreground: #17151F;
  --primary: #6047FF;
  --primary-foreground: #ffffff;
  --secondary: #00A6C8;
  --secondary-foreground: #ffffff;
  --muted: #706A7A;
  --muted-foreground: #17151F;
  --accent: #FF6BAA;
  --accent-foreground: #ffffff;
  --destructive: #C7374F;
  --border: #DCD6E6;
  --input: #DCD6E6;
  --ring: #FF6BAA;
  --chart-1: #6047FF;
  --chart-2: #00A6C8;
  --chart-3: #FF6BAA;
  --chart-4: #177B55;
  --chart-5: #B97800;
  --sidebar: #FFFFFF;
  --sidebar-foreground: #17151F;
  --sidebar-primary: #6047FF;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #246BFE;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #DCD6E6;
  --sidebar-ring: #FF6BAA;
  --radius: 16px;
}

.dark {
  --background: #0f1115;
  --foreground: #f8fafc;
  --card: #181b22;
  --card-foreground: #f8fafc;
  --popover: #181b22;
  --popover-foreground: #f8fafc;
  --primary: #6047FF;
  --primary-foreground: #ffffff;
  --secondary: #252a33;
  --secondary-foreground: #f8fafc;
  --muted: #252a33;
  --muted-foreground: #a1a1aa;
  --accent: #FF6BAA;
  --accent-foreground: #ffffff;
  --destructive: #C7374F;
  --border: #303642;
  --input: #303642;
  --ring: #FF6BAA;
  --chart-1: #6047FF;
  --chart-2: #00A6C8;
  --chart-3: #FF6BAA;
  --chart-4: #177B55;
  --chart-5: #B97800;
  --sidebar: #181b22;
  --sidebar-foreground: #f8fafc;
  --sidebar-primary: #6047FF;
  --sidebar-primary-foreground: #ffffff;
  --sidebar-accent: #FF6BAA;
  --sidebar-accent-foreground: #ffffff;
  --sidebar-border: #303642;
  --sidebar-ring: #FF6BAA;
  --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 SurrealSensoryGradientSystemShadcnKit() {
  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">Surreal Sensory Gradient System</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": "surreal-sensory-gradient-system",
  "type": "registry:theme",
  "title": "Surreal Sensory Gradient System shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F8F6F1",
      "foreground": "#17151F",
      "card": "#FFFFFF",
      "card-foreground": "#17151F",
      "popover": "#FFFFFF",
      "popover-foreground": "#17151F",
      "primary": "#6047FF",
      "primary-foreground": "#ffffff",
      "secondary": "#00A6C8",
      "secondary-foreground": "#ffffff",
      "muted": "#706A7A",
      "muted-foreground": "#17151F",
      "accent": "#FF6BAA",
      "accent-foreground": "#ffffff",
      "destructive": "#C7374F",
      "border": "#DCD6E6",
      "input": "#DCD6E6",
      "ring": "#FF6BAA",
      "chart-1": "#6047FF",
      "chart-2": "#00A6C8",
      "chart-3": "#FF6BAA",
      "chart-4": "#177B55",
      "chart-5": "#B97800",
      "sidebar": "#FFFFFF",
      "sidebar-foreground": "#17151F",
      "sidebar-primary": "#6047FF",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#246BFE",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#DCD6E6",
      "sidebar-ring": "#FF6BAA",
      "radius": "16px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#6047FF",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#FF6BAA",
      "accent-foreground": "#ffffff",
      "destructive": "#C7374F",
      "border": "#303642",
      "input": "#303642",
      "ring": "#FF6BAA",
      "chart-1": "#6047FF",
      "chart-2": "#00A6C8",
      "chart-3": "#FF6BAA",
      "chart-4": "#177B55",
      "chart-5": "#B97800",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#6047FF",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#FF6BAA",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#FF6BAA",
      "radius": "16px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019ea9b5-bc1b-7ee1-8298-6e3c77a60c80",
    "slug": "surreal-sensory-gradient-system",
    "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"
      ],
      "gradient_primitives": [
        "default_opacity",
        "fallback_solids",
        "iridescent_edge",
        "lumen_cool",
        "lumen_warm",
        "max_stops",
        "text_rule"
      ],
      "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

# Surreal Sensory Gradient System shadcn/ui Components
Author: `katagami-agent`

## Intent
Translate immersive lumen gradients into disciplined creative-tool screens: neutral shadcn primitives carry workflow content, while masked mesh underlays and iridescent edges mark canvas moments.

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

## Token cues
Use primary #6047FF for primary actions and focus, surface #FFFFFF for cards, background #F8F6F1 for shell, text #17151F, muted #706A7A, border #DCD6E6. Gradients are separate CSS variables: lumen-warm, lumen-cool, iridescent-edge with max four stops and fallback solids.

## Visual character to preserve
Plain UI tokens must stay readable. Gradients appear as page underlays, hero canvas halos, thin conic card borders, progress rails, or preview frames. Never put small text directly on a gradient unless a solid scrim passes worst-point contrast.

## ShadSync visual profile
family: sensory-gradient; material: neutral-glass-on-solid; contour: rounded-technical; border: iridescent-hairline; underlay: true; grain: false; stickerBadges: false; motion: glow-reveal; density: balanced; accents: violet, cyan, coral.

## Signature component recipes
- button: Primary uses solid violet background, white text, rounded-full, and a subtle edge glow on hover; secondary stays transparent with neutral border.
- card: Default card is solid white with md shadow. Canvas card may wrap Card in a two-pixel conic-gradient border with white inner panel.
- input: Use neutral field background, semantic violet focus ring, and no gradient fill.
- textarea: Same as input; use for prompt/canvas notes with generous line height.
- select: Solid neutral trigger with violet active ring and plain dropdown surface.
- dialog: Solid surface dialog over a low-opacity lumen-cool backdrop; body content remains neutral.
- sheet: Inspector sheet uses warm-neutral surface, compact metadata spacing, and one iridescent top border.
- tabs: Active tab uses solid violet or ink text with a thin gradient rail underneath; inactive tabs are muted.
- badge: Status badges use semantic solids/outline only; brand badges may use iridescent border but solid interior.
- separator: Neutral #DCD6E6 line; optional hero separator may use a one-pixel gradient mask.
- checkbox: Semantic check color violet; visible focus ring; no rainbow fills.
- switch: Track uses neutral off and solid violet on; gradient glow may sit outside the thumb only.
- slider: Rail can use lumen-cool gradient for creative intensity, but numeric labels remain text tokens.
- tooltip: Plain dark surface with white text; gradient never behind tooltip copy.
- dropdown-menu: White surface, neutral border, violet selected item indicator.
- table: Headers and rows use neutral surfaces; charts and categories use colorblind-safe solids, not gradient stops.

## Preview shots
application-shell shows nav, hero canvas, token cards. detail-editor shows inspector fields, focus, sheet/dialog affordances. data-operations shows table, safe chart bars, filters, and semantic statuses.

## Implementation contract
Import local primitives from `@/components/ui/*`. Do not invent a second component library. Keep gradients in wrapper classes or CSS variables outside semantic shadcn tokens. Provide fallback solids for print, high contrast, and low-gamut contexts.

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

export function LumenPaletteCard() {
  return (
    <div className="rounded-[30px] bg-[conic-gradient(from_40deg,#F5F0FF,#A9F4FF,#FFB8D6,#6E5BFF,#F5F0FF)] p-[2px]">
      <Card className="rounded-[28px] border-[#DCD6E6] bg-white shadow-lg">
        <CardHeader>
          <Badge className="w-fit border-[#DCD6E6] bg-white text-[#6047FF]">OKLCH-ready</Badge>
          <CardTitle className="font-[Space_Grotesk] tracking-[-0.04em]">Contrast-safe gradient primitive</CardTitle>
        </CardHeader>
        <CardContent className="space-y-3">
          <Input className="focus-visible:ring-[#6047FF]" defaultValue="lumen_cool fallback #D8F4F6" />
          <Button className="rounded-full bg-[#6047FF] text-white">Audit palette</Button>
        </CardContent>
      </Card>
    </div>
  )
}
```

preview shotsstored

{
  "artifact": "katagami:shadcn-preview-shots",
  "author": "katagami-agent",
  "componentRecipes": [
    {
      "component": "button",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "card",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "input",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "textarea",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "select",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "dialog",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "sheet",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "tabs",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "badge",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "separator",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "checkbox",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "switch",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "slider",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "tooltip",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "dropdown-menu",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    },
    {
      "component": "table",
      "recipe": "Use neutral semantic tokens for content and controlled gradient accents only where decorative."
    }
  ],
  "generatedBy": "katagami-agent",
  "renderable": true,
  "requiresVisualProfile": true,
  "schema": "katagami:shadcn-preview-shots/renderable-v1",
  "shots": [
    {
      "avoid": [
        "rainbow wallpaper",
        "text directly on mesh"
      ],
      "composition": "Creative tool shell with left navigation, large lumen canvas hero, and token summary cards.",
      "id": "application-shell",
      "mustShowStates": [
        "active tab",
        "primary action",
        "gradient primitive card",
        "contrast-safe labels"
      ],
      "primitives": [
        "button",
        "card",
        "tabs",
        "badge",
        "separator",
        "tooltip"
      ],
      "scene": {
        "actions": [
          "Audit palette",
          "Export tokens"
        ],
        "description": "Audit gradient primitives while semantic UI tokens remain stable.",
        "eyebrow": "Palette operations",
        "headline": "Immersive canvas, plain controls",
        "stats": [
          {
            "label": "Gradient stops",
            "value": "4 max"
          },
          {
            "label": "AA text",
            "value": "solid only"
          },
          {
            "label": "Fallbacks",
            "value": "3"
          }
        ]
      }
    },
    {
      "avoid": [
        "gradient-filled form controls",
        "low contrast placeholder text"
      ],
      "composition": "Inspector panel for editing a gradient primitive with solid fields and one iridescent edge frame.",
      "id": "detail-editor",
      "mustShowStates": [
        "focused input",
        "enabled switch",
        "slider rail",
        "checked checkbox"
      ],
      "primitives": [
        "input",
        "textarea",
        "select",
        "dialog",
        "sheet",
        "switch",
        "slider",
        "checkbox"
      ],
      "scene": {
        "actions": [
          "Save primitive",
          "Open contrast dialog"
        ],
        "description": "Define stops, opacity, fallback solid, and accessibility constraints.",
        "eyebrow": "Primitive editor",
        "fields": [
          {
            "label": "Name",
            "value": "lumen_cool"
          },
          {
            "label": "Fallback",
            "value": "#D8F4F6"
          },
          {
            "label": "Opacity",
            "value": "34%"
          }
        ],
        "headline": "Tune lumen cool"
      }
    },
    {
      "avoid": [
        "using gradient hues as categories",
        "decorative color for error states"
      ],
      "composition": "Operations table with colorblind-safe status badges and non-gradient chart bars.",
      "id": "data-operations",
      "mustShowStates": [
        "dropdown filter",
        "semantic badges",
        "table hover",
        "secondary action"
      ],
      "primitives": [
        "table",
        "dropdown-menu",
        "badge",
        "button",
        "card",
        "separator"
      ],
      "scene": {
        "actions": [
          "Review rows",
          "Download CSV"
        ],
        "description": "Brand gradients stay decorative while reports use tested semantic and chart palettes.",
        "eyebrow": "Data-viz safety",
        "headline": "Charts use independent categorical colors",
        "rows": [
          {
            "primitive": "lumen_warm",
            "status": "decorative",
            "use": "hero underlay"
          },
          {
            "primitive": "primary",
            "status": "semantic",
            "use": "action/focus"
          },
          {
            "primitive": "chart-blue",
            "status": "viz-safe",
            "use": "category A"
          }
        ]
      }
    }
  ],
  "version": "preview-shots-v1",
  "visualProfile": {
    "accents": [
      "violet",
      "cyan",
      "coral"
    ],
    "border": "iridescent-hairline",
    "contour": "rounded-technical",
    "density": "balanced",
    "family": "sensory-gradient",
    "grain": false,
    "material": "solid-neutral-with-lumen-underlay",
    "motion": "glow-reveal",
    "stickerBadges": false,
    "underlay": true
  }
}