Velatura

# Velatura

## Philosophy

Velatura is a crafted-sheet interface system painted in saturated digital watercolor. It builds product surfaces from pooled, luminous pigment instead of mechanical lines — a sheet that feels authored by a hand, yet stays exact where it counts. One physical behaviour runs the whole system: drop saturated colour into wet paper and it blooms, deepest at the source and feathering out at the edge. That bloom is mapped onto the moments that matter — the primary action, the active row, the selected state, the alert — while everything quieter steps back to a thin wash or plain ink. Warmth is reserved, not sprayed; the rest of the sheet breathes as unpainted paper. Type, spacing, and alignment stay disciplined for real product use, so the language rejects both sterile software flatness and retro craft theatre. It suits editorial tools, wellbeing apps, creative utilities, education, and slow-tech — anywhere trust and humane pacing earn their keep.

### Values

- tactility
- humane pacing
- luminous saturation
- reserved warmth
- disciplined clarity

### Anti-Values

- muddy or muted colour
- borders and boxed chrome
- scrapbook sentimentality
- sterile flatness
- decoration without an idea

## Tokens

### Colors

| Name | Value |
|------|-------|
| bg | `#FCFAF5` |
| surface | `#FFFFFF` |
| text | `#1C2433` |
| muted | `#6B7280` |
| border | `#ECE4D6` |
| accent | `#11A7B8` |
| accent_2 | `#F2604A` |
| accent_3 | `#F2B23C` |
| on_accent | `#FFFFFF` |
| success | `#2E9E6B` |
| warning | `#E0962B` |
| error | `#E0524A` |
| info | `#2C8FB5` |

### Typography

- **Base Size**: 17px
- **Body Font**: Inter
- **Heading Font**: Fraunces
- **Mono Font**: IBM Plex Mono
- **Heading Weight**: 600
- **Heading Transform**: none
- **Letter Spacing**: -0.022em
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,500;9..144,600;9..144,700&family=Inter:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500&display=swap

### Radii

- **None**: 0
- **Card**: 16px
- **Lg**: 24px
- **Full**: 9999px

### Shadows

- **Sm**: 0 8px 18px -10px rgba(28,36,51,.12)
- **Md**: 0 18px 44px -22px rgba(28,36,51,.20)
- **Lg**: 0 30px 64px -28px rgba(17,167,184,.30)

### Spacing

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

### Surfaces

- **Treatment**: watercolor-vellum
- **Card Style**: White vellum sheet on a radiant warm-paper ground; soft warm shadow elevation; a faint pigment wash in one corner; no borders.
- **Bg Pattern**: faint perimeter pigment washes

### Borders

- **Default Width**: 0
- **Accent Width**: 0
- **Style**: none
- **Character**: No borders; separation by soft shadow and a single wet brush-pass divider. Inputs carry a soft inset mineral wash-line, never a hard rule.

### Motion

- **Reveal**: sections rise slowly on scroll like pigment settling
- **Default State**: fully-rendered, settled, visible with no JS
- **Reduced Motion**: respected — reveal disabled

## Rules

### Composition

One atmospheric hero zone, then disciplined vellum panels; broad open margins paired with dense islands of information so the page feels painted, not templated. Brush-pass dividers separate sections. Reserve the deepest pigment for active moments and the primary call to action; empty space reads as unpainted paper.

### Hierarchy

Display headlines in Fraunces carry the emotional tone, with a colour-pop highlighter on one word; body and controls in Inter stay immediate at 17px+; metadata and numerics in IBM Plex Mono, restrained and tabular. Highest hierarchy combines type scale, deeper ink, and stronger pigment concentration — not more chrome.

### Density

Generous and breathing; dense data islands stay strictly aligned inside soft surfaces.

### Signature

The bloom — a charged radial pigment pool (deep core, feathered rim) marks the primary or active element and recolours through buttons, selection states, alerts, charts, and meters; quieter elements drop to a thin wash or plain ink.

## Layout

### Grid

12-col fluid, max content width ~1160px; only the full-bleed hero spans 100vw.

### Whitespace

Generous; padding always above titles; empty space reads as paper.

### Density

Airy overall, with strictly-aligned dense data islands.

### Responsive

Single column under 860px; nav links hide on small screens; sidebar reflows to a top row; hero headline uses clamp() and wraps, never clipping at 390px.

### Breakpoints

- **Sm**: 560px
- **Md**: 860px
- **Lg**: 1000px
- **Xl**: 1280px

## Guidance

### Do

- Reserve the deepest pigment for the single most important action on a screen.
- Let empty space read as unpainted paper, not a gap to fill.
- Separate sections with a wet brush pass; keep internal alignment strict.
- Keep colour bright and humid — never muted, never muddy.

### Don't

- Don't border the cards or trap the nav in a boxed pill bar.
- Don't let two accents compete; let one recede.
- Don't soften type or alignment in the name of warmth.
- Don't use an upright/italic serif word-swap headline.

### Accessibility

Body 17px+; deep cool ink on radiant paper holds high contrast; focus blooms the accent with a visible halo; motion respects prefers-reduced-motion; status uses a labelled pigment dot, never colour alone.

## Imagery Direction

### Pairs With

wetwash

### Summary

Saturated wet-into-wet digital watercolor: pooled luminous pigment, feathered edges, layered transparent glazes, backruns, granulating texture, jewel tones at full brightness on radiant paper. Hero is a single charged bloom with a calm paper third for the headline.

### Subjects

- a single charged pigment bloom across wet paper
- a portrait dissolved into blooming colour
- a city skyline of pooled washes
- a still-life object built from glazes

### Usage

Hero is full-bleed with a calm left third for an overlaid headline; feature and avatar slots crop tight on a single subject; empty-state is a faint pale wash.

---
version: "alpha"
name: "Velatura"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  bg: "#FCFAF5"
  surface: "#FFFFFF"
  text: "#1C2433"
  muted: "#6B7280"
  border: "#ECE4D6"
  accent: "#11A7B8"
  accent_2: "#F2604A"
  accent_3: "#F2B23C"
  on_accent: "#FFFFFF"
  success: "#2E9E6B"
  warning: "#E0962B"
  error: "#E0524A"
  info: "#2C8FB5"
typography:
  headline-lg:
    fontFamily: "Fraunces"
    fontSize: "2.075rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.022em"
  headline-md:
    fontFamily: "Fraunces"
    fontSize: "1.66rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.022em"
  body-md:
    fontFamily: "Inter"
    fontSize: "17px"
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: "-0.022em"
  label-md:
    fontFamily: "IBM Plex Mono"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
rounded:
  none: "0px"
  card: "16px"
  lg: "24px"
  full: "9999px"
spacing:
  base: "8px"
  xs: "4px"
  sm: "8px"
  md: "12px"
  lg: "16px"
  xl: "24px"
  2xl: "32px"
  3xl: "48px"
  4xl: "64px"
  step-8: "88px"
components:
  color-reference-bg:
    backgroundColor: "{colors.bg}"
  color-reference-surface:
    backgroundColor: "{colors.surface}"
  color-reference-text:
    backgroundColor: "{colors.text}"
  color-reference-muted:
    backgroundColor: "{colors.muted}"
  color-reference-border:
    backgroundColor: "{colors.border}"
  color-reference-accent:
    backgroundColor: "{colors.accent}"
  color-reference-accent_2:
    backgroundColor: "{colors.accent_2}"
  color-reference-accent_3:
    backgroundColor: "{colors.accent_3}"
  color-reference-on_accent:
    backgroundColor: "{colors.on_accent}"
  color-reference-success:
    backgroundColor: "{colors.success}"
  color-reference-warning:
    backgroundColor: "{colors.warning}"
  color-reference-error:
    backgroundColor: "{colors.error}"
  color-reference-info:
    backgroundColor: "{colors.info}"
  button-primary:
    backgroundColor: "{colors.accent}"
    textColor: "#000000"
    typography: "{typography.label-md}"
    rounded: "{rounded.lg}"
    padding: "{spacing.md}"
  card-surface:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text}"
    rounded: "{rounded.lg}"
    padding: "{spacing.md}"
  input-default:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text}"
    rounded: "{rounded.lg}"
    height: "44px"
---

# Velatura

## Overview

Velatura is a crafted-sheet interface system painted in saturated digital watercolor. It builds product surfaces from pooled, luminous pigment instead of mechanical lines — a sheet that feels authored by a hand, yet stays exact where it counts. One physical behaviour runs the whole system: drop saturated colour into wet paper and it blooms, deepest at the source and feathering out at the edge. That bloom is mapped onto the moments that matter — the primary action, the active row, the selected state, the alert — while everything quieter steps back to a thin wash or plain ink. Warmth is reserved, not sprayed; the rest of the sheet breathes as unpainted paper. Type, spacing, and alignment stay disciplined for real product use, so the language rejects both sterile software flatness and retro craft theatre. It suits editorial tools, wellbeing apps, creative utilities, education, and slow-tech — anywhere trust and humane pacing earn their keep.

### Values

- tactility
- humane pacing
- luminous saturation
- reserved warmth
- disciplined clarity

### Anti-Values

- muddy or muted colour
- borders and boxed chrome
- scrapbook sentimentality
- sterile flatness
- decoration without an idea

## Colors

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

| Token | Value |
|-------|-------|
| bg | `#FCFAF5` |
| surface | `#FFFFFF` |
| text | `#1C2433` |
| muted | `#6B7280` |
| border | `#ECE4D6` |
| accent | `#11A7B8` |
| accent_2 | `#F2604A` |
| accent_3 | `#F2B23C` |
| on_accent | `#FFFFFF` |
| success | `#2E9E6B` |
| warning | `#E0962B` |
| error | `#E0524A` |
| info | `#2C8FB5` |

## Typography

- **Headline-Lg**: Fraunces, 2.075rem, weight 700, line-height 1.1.
- **Headline-Md**: Fraunces, 1.66rem, weight 600, line-height 1.15.
- **Body-Md**: Inter, 17px, weight 400, line-height 1.5.
- **Label-Md**: IBM Plex Mono, 0.75rem, weight 600, line-height 1.

## Layout

### Spacing Tokens

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

### Grid

12-col fluid, max content width ~1160px; only the full-bleed hero spans 100vw.

### Whitespace

Generous; padding always above titles; empty space reads as paper.

### Density

Airy overall, with strictly-aligned dense data islands.

### Responsive

Single column under 860px; nav links hide on small screens; sidebar reflows to a top row; hero headline uses clamp() and wraps, never clipping at 390px.

### Breakpoints

- **Sm**: 560px
- **Md**: 860px
- **Lg**: 1000px
- **Xl**: 1280px

## Elevation & Depth

### Shadows

- **Sm**: 0 8px 18px -10px rgba(28,36,51,.12)
- **Md**: 0 18px 44px -22px rgba(28,36,51,.20)
- **Lg**: 0 30px 64px -28px rgba(17,167,184,.30)

## Shapes

### Rounded

- **None**: `0px`
- **Card**: `16px`
- **Lg**: `24px`
- **Full**: `9999px`

### Surfaces

- **Treatment**: watercolor-vellum
- **Card Style**: White vellum sheet on a radiant warm-paper ground; soft warm shadow elevation; a faint pigment wash in one corner; no borders.
- **Bg Pattern**: faint perimeter pigment washes

### Borders

- **Default Width**: 0
- **Accent Width**: 0
- **Style**: none
- **Character**: No borders; separation by soft shadow and a single wet brush-pass divider. Inputs carry a soft inset mineral wash-line, never a hard rule.

## Components

### Composition

One atmospheric hero zone, then disciplined vellum panels; broad open margins paired with dense islands of information so the page feels painted, not templated. Brush-pass dividers separate sections. Reserve the deepest pigment for active moments and the primary call to action; empty space reads as unpainted paper.

### Hierarchy

Display headlines in Fraunces carry the emotional tone, with a colour-pop highlighter on one word; body and controls in Inter stay immediate at 17px+; metadata and numerics in IBM Plex Mono, restrained and tabular. Highest hierarchy combines type scale, deeper ink, and stronger pigment concentration — not more chrome.

### Density

Generous and breathing; dense data islands stay strictly aligned inside soft surfaces.

### Signature

The bloom — a charged radial pigment pool (deep core, feathered rim) marks the primary or active element and recolours through buttons, selection states, alerts, charts, and meters; quieter elements drop to a thin wash or plain ink.

## 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-019efd9f-e601-71e1-bb0e-34802e495908/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 Reserve the deepest pigment for the single most important action on a screen.
- Do Let empty space read as unpainted paper, not a gap to fill.
- Do Separate sections with a wet brush pass; keep internal alignment strict.
- Do Keep colour bright and humid — never muted, never muddy.
- Don't Don't border the cards or trap the nav in a boxed pill bar.
- Don't Don't let two accents compete; let one recede.
- Don't Don't soften type or alignment in the name of warmth.
- Don't Don't use an upright/italic serif word-swap headline.

### Accessibility

Body 17px+; deep cool ink on radiant paper holds high contrast; focus blooms the accent with a visible halo; motion respects prefers-reduced-motion; status uses a labelled pigment dot, never colour alone.

## Imagery Direction

### Pairs With

wetwash

### Summary

Saturated wet-into-wet digital watercolor: pooled luminous pigment, feathered edges, layered transparent glazes, backruns, granulating texture, jewel tones at full brightness on radiant paper. Hero is a single charged bloom with a calm paper third for the headline.

### Subjects

- a single charged pigment bloom across wet paper
- a portrait dissolved into blooming colour
- a city skyline of pooled washes
- a still-life object built from glazes

### Usage

Hero is full-bleed with a calm left third for an overlaid headline; feature and avatar slots crop tight on a single subject; empty-state is a faint pale wash.

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "velatura",
  "type": "registry:theme",
  "title": "Velatura shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#FCFAF5",
      "foreground": "#1C2433",
      "card": "#FFFFFF",
      "card-foreground": "#1C2433",
      "popover": "#FFFFFF",
      "popover-foreground": "#1C2433",
      "primary": "#1C2433",
      "primary-foreground": "#ffffff",
      "secondary": "#f4f4f5",
      "secondary-foreground": "#111111",
      "muted": "#6B7280",
      "muted-foreground": "#1C2433",
      "accent": "#11A7B8",
      "accent-foreground": "#ffffff",
      "destructive": "#E0524A",
      "border": "#ECE4D6",
      "input": "#ECE4D6",
      "ring": "#11A7B8",
      "chart-1": "#1C2433",
      "chart-2": "#f4f4f5",
      "chart-3": "#11A7B8",
      "chart-4": "#2E9E6B",
      "chart-5": "#E0962B",
      "sidebar": "#FFFFFF",
      "sidebar-foreground": "#1C2433",
      "sidebar-primary": "#1C2433",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#2C8FB5",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#ECE4D6",
      "sidebar-ring": "#11A7B8",
      "radius": "24px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#1C2433",
      "primary-foreground": "#ffffff",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#11A7B8",
      "accent-foreground": "#ffffff",
      "destructive": "#E0524A",
      "border": "#303642",
      "input": "#303642",
      "ring": "#11A7B8",
      "chart-1": "#1C2433",
      "chart-2": "#f4f4f5",
      "chart-3": "#11A7B8",
      "chart-4": "#2E9E6B",
      "chart-5": "#E0962B",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#1C2433",
      "sidebar-primary-foreground": "#ffffff",
      "sidebar-accent": "#11A7B8",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#11A7B8",
      "radius": "24px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019efd9f-e601-71e1-bb0e-34802e495908",
    "slug": "velatura",
    "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": {
      "colors": [
        "accent",
        "accent_2",
        "accent_3",
        "bg",
        "border",
        "error",
        "info",
        "muted",
        "on_accent",
        "success",
        "surface",
        "text",
        "warning"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "heading_transform",
        "heading_weight",
        "letter_spacing",
        "mono_font"
      ],
      "radii": [
        "card",
        "full",
        "lg",
        "none"
      ],
      "shadows": [
        "lg",
        "md",
        "sm"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "borders": [
        "accent_width",
        "character",
        "default_width",
        "style"
      ],
      "motion": [
        "default_state",
        "reduced_motion",
        "reveal"
      ]
    }
  }
}
```