Elemental Tech Neutrals

# Elemental Tech Neutrals

## Philosophy

Elemental Tech Neutrals is a production-first palette system for modern digital products that balances mineral value discipline, clay warmth, graphite authority, sand tactility, and restrained botanical undertones with one precise digital accent reserved for interaction and state. It treats neutral surfaces as durable product infrastructure rather than background filler.

### Values

- crisp neutral hierarchy
- warm cool surface balance
- semantic token readiness
- accessibility before atmosphere
- digital accent restraint

### Anti-Values

- beige mush without value steps
- decorative chroma spread across every card
- hue swapping between light and dark modes
- low-contrast graphite text on clay fields

### Visual Character

- Layer warm sand and clay panels against cooler mineral and graphite rails using explicit CSS variables for every surface role.
- Use 1px graphite-clay borders plus 2px high-contrast focus rings so UI boundaries remain visible without heavy shadows.
- Reserve a single cobalt-cyan digital accent for CTAs, selected tabs, active rows, and status pips rather than broad fills.
- Apply fine mineral grain and subtle contour-line underlays only on large background planes, never on text-bearing controls.
- Invert tonal values for dark mode while keeping the same hue families, preserving named roles instead of swapping palette intent.

## Tokens

### Borders

- **Accent Width**: 2px
- **Character**: crisp graphite-clay separators with high-value step between adjacent surfaces
- **Default Width**: 1px
- **Style**: solid

### Colors

| Name | Value |
|------|-------|
| accent | `#1F8BFF` |
| background | `#F4F0E7` |
| border | `#BDB4A4` |
| error | `#B8423A` |
| info | `#326B8C` |
| muted | `#6E716B` |
| primary | `#24313A` |
| secondary | `#8E7963` |
| success | `#31785B` |
| surface | `#FFFCF4` |
| text | `#1B2024` |
| warning | `#A66B16` |

### Motion

- **Duration**: 160ms
- **Easing**: cubic-bezier(0.2, 0, 0.1, 1)
- **Philosophy**: fast utilitarian confirmation; focus and selected states change by value and border before color

### Radii

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

### Shadows

- **Lg**: 0 24px 80px rgba(36,49,58,0.16)
- **Md**: 0 10px 30px rgba(36,49,58,0.10)
- **Sm**: 0 1px 0 rgba(36,49,58,0.12)

### Spacing

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

### Surfaces

- **Bg Pattern**: low-opacity mineral grain plus sparse contour lines on non-interactive background areas
- **Card Style**: flat cards with visible 1px borders, topographic corner ticks, and narrow accent rule only for selected states
- **Treatment**: matte mineral planes with warm clay insets and cool graphite navigation zones

### Typography

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

## Rules

### Composition

Build product screens from a cool graphite command rail, warm sand work surface, and crisp white-mineral cards. Maintain visible gutters and role-based planes so neutral layers do not collapse into beige mush.

### Density

Moderately dense enterprise/editorial density with 8px rhythm, compact controls, generous section gutters, and no ornamental whitespace padding.

### Hierarchy

Lead with dense but calm typographic hierarchy: IBM Plex Sans headings, Source Sans body labels, and IBM Plex Mono for tokens, measurements, IDs, contrast ratios, and operational metadata.

### Signature Patterns

- Mineral stratum cards use a 1px border, inset top value band, and tiny corner coordinate marks drawn with pseudo-elements.
- Clay audit strips sit beside forms and tables as semantic role labels, using warm fill and graphite text instead of badges everywhere.
- Digital accent appears as narrow rules, focus halos, selected row pips, and one primary CTA fill, never as broad decorative gradients.
- Data panels separate neutral qualitative content from chromatic quantitative marks with patterned lines for colorblind-safe comparison.

## Layout

### Breakpoints

mobile 375px single-column, tablet 768px two-zone stack, desktop 1200px+ rail plus content matrix

### Grid

12-column desktop grid with 280px graphite rail, 24px gutters, and card interiors aligned to an 8px baseline.

### Whitespace

Whitespace is functional separation: 16px inside controls, 24px between cards, 32px between operational zones.

## Guidance

### Do

- Use named semantic roles for surface, surface-warm, surface-cool, text, border, action, focus, and status before adding component colors.
- Verify 4.5:1 text contrast and 3:1 UI boundaries for every neutral pairing in both light and dark modes.
- Keep the digital accent for primary action, keyboard focus, active navigation, and urgent live state markers.
- Use pattern, value, and labels for chart categories so data remains colorblind safe.

### Don't

- Do not wash entire screens in beige or use adjacent neutrals with indistinct values.
- Do not introduce multiple saturated brand hues for decorative variety.
- Do not swap hue families in dark mode; invert tones and preserve token roles.
- Do not place text directly over grain, contour lines, or gradients.

---
version: "alpha"
name: "Elemental Tech Neutrals"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  accent: "#1F8BFF"
  background: "#F4F0E7"
  border: "#BDB4A4"
  error: "#B8423A"
  info: "#326B8C"
  muted: "#6E716B"
  primary: "#24313A"
  secondary: "#8E7963"
  success: "#31785B"
  surface: "#FFFCF4"
  text: "#1B2024"
  warning: "#A66B16"
typography:
  headline-lg:
    fontFamily: "IBM Plex Sans"
    fontSize: "1.816rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.01em"
  headline-md:
    fontFamily: "IBM Plex Sans"
    fontSize: "1.488rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.01em"
  body-md:
    fontFamily: "Source Sans 3"
    fontSize: "16px"
    fontWeight: 400
    lineHeight: 1.52
    letterSpacing: "-0.01em"
  label-md:
    fontFamily: "IBM Plex Mono"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
rounded:
  full: "9999px"
  lg: "10px"
  md: "6px"
  none: "0px"
  sm: "3px"
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"
---

# Elemental Tech Neutrals

## Overview

Elemental Tech Neutrals is a production-first palette system for modern digital products that balances mineral value discipline, clay warmth, graphite authority, sand tactility, and restrained botanical undertones with one precise digital accent reserved for interaction and state. It treats neutral surfaces as durable product infrastructure rather than background filler.

### Values

- crisp neutral hierarchy
- warm cool surface balance
- semantic token readiness
- accessibility before atmosphere
- digital accent restraint

### Anti-Values

- beige mush without value steps
- decorative chroma spread across every card
- hue swapping between light and dark modes
- low-contrast graphite text on clay fields

### Visual Character

- Layer warm sand and clay panels against cooler mineral and graphite rails using explicit CSS variables for every surface role.
- Use 1px graphite-clay borders plus 2px high-contrast focus rings so UI boundaries remain visible without heavy shadows.
- Reserve a single cobalt-cyan digital accent for CTAs, selected tabs, active rows, and status pips rather than broad fills.
- Apply fine mineral grain and subtle contour-line underlays only on large background planes, never on text-bearing controls.
- Invert tonal values for dark mode while keeping the same hue families, preserving named roles instead of swapping palette intent.

## 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 | `#1F8BFF` |
| background | `#F4F0E7` |
| border | `#BDB4A4` |
| error | `#B8423A` |
| info | `#326B8C` |
| muted | `#6E716B` |
| primary | `#24313A` |
| secondary | `#8E7963` |
| success | `#31785B` |
| surface | `#FFFCF4` |
| text | `#1B2024` |
| warning | `#A66B16` |

## Typography

- **Headline-Lg**: IBM Plex Sans, 1.816rem, weight 700, line-height 1.1.
- **Headline-Md**: IBM Plex Sans, 1.488rem, weight 600, line-height 1.15.
- **Body-Md**: Source Sans 3, 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 single-column, tablet 768px two-zone stack, desktop 1200px+ rail plus content matrix

### Grid

12-column desktop grid with 280px graphite rail, 24px gutters, and card interiors aligned to an 8px baseline.

### Whitespace

Whitespace is functional separation: 16px inside controls, 24px between cards, 32px between operational zones.

## Elevation & Depth

### Shadows

- **Lg**: 0 24px 80px rgba(36,49,58,0.16)
- **Md**: 0 10px 30px rgba(36,49,58,0.10)
- **Sm**: 0 1px 0 rgba(36,49,58,0.12)

## Shapes

### Rounded

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

### Surfaces

- **Bg Pattern**: low-opacity mineral grain plus sparse contour lines on non-interactive background areas
- **Card Style**: flat cards with visible 1px borders, topographic corner ticks, and narrow accent rule only for selected states
- **Treatment**: matte mineral planes with warm clay insets and cool graphite navigation zones

### Borders

- **Accent Width**: 2px
- **Character**: crisp graphite-clay separators with high-value step between adjacent surfaces
- **Default Width**: 1px
- **Style**: solid

## Components

### Composition

Build product screens from a cool graphite command rail, warm sand work surface, and crisp white-mineral cards. Maintain visible gutters and role-based planes so neutral layers do not collapse into beige mush.

### Density

Moderately dense enterprise/editorial density with 8px rhythm, compact controls, generous section gutters, and no ornamental whitespace padding.

### Hierarchy

Lead with dense but calm typographic hierarchy: IBM Plex Sans headings, Source Sans body labels, and IBM Plex Mono for tokens, measurements, IDs, contrast ratios, and operational metadata.

### Signature Patterns

- Mineral stratum cards use a 1px border, inset top value band, and tiny corner coordinate marks drawn with pseudo-elements.
- Clay audit strips sit beside forms and tables as semantic role labels, using warm fill and graphite text instead of badges everywhere.
- Digital accent appears as narrow rules, focus halos, selected row pips, and one primary CTA fill, never as broad decorative gradients.
- Data panels separate neutral qualitative content from chromatic quantitative marks with patterned lines for colorblind-safe comparison.

## 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-5d38-7800-b9df-aef305e833bf/DESIGN.with-shadcn.md`.

The shadcn page also exposes optional machine-readable files for automation, but the human-facing handoff is DESIGN.md with shadcn.

Install recommended primitives with `npx shadcn@latest add button card input textarea select dialog sheet tabs badge separator checkbox switch slider tooltip dropdown-menu table`.

Use these primitives in shadcn apps:
- button
- card
- input
- textarea
- select
- dialog
- sheet
- tabs
- badge
- separator
- checkbox
- switch
- slider
- tooltip
- dropdown-menu
- table

Implementation rule for agents: import shadcn primitives from `@/components/ui/*`, apply the generated CSS variables first, then compose the language-specific recipes from the companion MD. Katagami remains the source of truth; shadcn names are the implementation surface.

## Do's and Don'ts

- Do Use named semantic roles for surface, surface-warm, surface-cool, text, border, action, focus, and status before adding component colors.
- Do Verify 4.5:1 text contrast and 3:1 UI boundaries for every neutral pairing in both light and dark modes.
- Do Keep the digital accent for primary action, keyboard focus, active navigation, and urgent live state markers.
- Do Use pattern, value, and labels for chart categories so data remains colorblind safe.
- Don't Do not wash entire screens in beige or use adjacent neutrals with indistinct values.
- Don't Do not introduce multiple saturated brand hues for decorative variety.
- Don't Do not swap hue families in dark mode; invert tones and preserve token roles.
- Don't Do not place text directly over grain, contour lines, or gradients.

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "elemental-tech-neutrals",
  "type": "registry:theme",
  "title": "Elemental Tech Neutrals shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#F4F0E7",
      "foreground": "#1B2024",
      "card": "#FFFCF4",
      "card-foreground": "#1B2024",
      "popover": "#FFFCF4",
      "popover-foreground": "#1B2024",
      "primary": "#24313A",
      "primary-foreground": "#ffffff",
      "secondary": "#8E7963",
      "secondary-foreground": "#ffffff",
      "muted": "#6E716B",
      "muted-foreground": "#1B2024",
      "accent": "#1F8BFF",
      "accent-foreground": "#ffffff",
      "destructive": "#B8423A",
      "border": "#BDB4A4",
      "input": "#BDB4A4",
      "ring": "#1F8BFF",
      "chart-1": "#24313A",
      "chart-2": "#8E7963",
      "chart-3": "#1F8BFF",
      "chart-4": "#31785B",
      "chart-5": "#A66B16",
      "sidebar": "#FFFCF4",
      "sidebar-foreground": "#1B2024",
      "sidebar-primary": "#24313A",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#326B8C",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#BDB4A4",
      "sidebar-ring": "#1F8BFF",
      "radius": "6px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#24313A",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#1F8BFF",
      "accent-foreground": "#ffffff",
      "destructive": "#B8423A",
      "border": "#303642",
      "input": "#303642",
      "ring": "#1F8BFF",
      "chart-1": "#24313A",
      "chart-2": "#8E7963",
      "chart-3": "#1F8BFF",
      "chart-4": "#31785B",
      "chart-5": "#A66B16",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#24313A",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#1F8BFF",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#1F8BFF",
      "radius": "6px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019ea9b1-5d38-7800-b9df-aef305e833bf",
    "slug": "elemental-tech-neutrals",
    "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"
      ]
    }
  }
}
```