Phosphene

# Phosphene

## Philosophy

Phosphene reads the screen as a field of discrete glowing cells. Its one ownable idea is the cell meter: every quantity — capacity, signal, progress, load — is drawn as a run of lit and unlit square cells, and the colour of those cells carries operational state. Forms are built by counting light, not by smoothing it. The result is an instrument-panel language that stays calm and legible on a deep dark-glass ground, where a few bright inks behave like highlighters on glass.

### Values

- Quantize value: show amounts as counted cells, not smooth bars, so every reading is discrete and machine-honest.
- Let colour carry state: amber is active, cyan is idle or informational, magenta is a peak or a fault.
- Stay on dark glass: the deep ground makes lit cells and accents read as emitted light.
- Build hierarchy from light and space, not from boxes and edges.
- Keep it usable, not a costume: an instrument you would actually read, not retro decoration.

### Anti-Values

- Scanline and dither texture smeared across every surface as nostalgia wallpaper.
- Embossed dual-edge bevels stamped on every panel and button until they are noise.
- Smooth gradient meters and glossy charts that hide the discrete reading.
- Grey card borders and a single accent edge framing every module.
- Defaulting to a white page; this language lives on dark glass.

### Visual Character

- The cell meter is everywhere: capacities, progress, signal and load all render as rows or grids of square cells, lit cells in the accent ink and unlit cells as faint ghost squares on the ground.
- Lit cells carry a soft additive bloom, so an active reading glows against the dark glass like phosphor while an idle one sits quiet.
- Type is a clean technical sans for body and labels with a tabular monospace for numerals and readouts, so columns of figures line up cell-true.
- Status is told in three inks — amber active, cyan idle or info, magenta peak or fault — used like highlighters, never as fills.
- Surfaces are flat dark-glass planes separated by space and a faint lift, not by borders or bevels; corners are square or softly rounded, never pill-shaped.

## Tokens

### Colors

| Name | Value |
|------|-------|
| primary | `#FFB72E` |
| secondary | `#38E1D6` |
| accent | `#FF4D8D` |
| background | `#0B1020` |
| surface | `#141A2E` |
| text | `#F2EFE6` |
| muted | `#8A93AD` |
| border | `#222A42` |
| on_accent | `#0B1020` |
| error | `#FF5C6A` |
| success | `#5BE3A0` |
| warning | `#FFB72E` |
| info | `#38E1D6` |

### Typography

- **Heading Font**: Space Grotesk, sans-serif
- **Body Font**: Inter, sans-serif
- **Mono Font**: Space Mono, monospace
- **Base Size**: 17px
- **Scale Ratio**: 1.2
- **Line Height**: 1.55
- **Letter Spacing**: -0.01em
- **Heading Weight**: 600
- **Heading Transform**: none
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Space+Grotesk:wght@500;600;700&family=Space+Mono:wght@400;700&display=swap

### Spacing

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

### Radii

- **None**: 0px
- **Sm**: 0px
- **Md**: 16px
- **Lg**: 16px
- **Xl**: 24px
- **Full**: 9999px

### Shadows

- **Sm**: 0 0 0 transparent
- **Md**: 0 8px 24px rgba(0,0,0,0.45)
- **Lg**: 0 16px 48px rgba(0,0,0,0.55)
- **Glow**: 0 0 18px rgba(255,183,46,0.35)

### Surfaces

- **Treatment**: flat
- **Card Style**: Flat dark-glass planes lifted from the ground by a hair of fill and a soft shadow; no borders, no bevels.
- **Bg Pattern**: cell-grid

### Borders

- **Default Width**: 0px
- **Accent Width**: 0px
- **Style**: none
- **Character**: Hierarchy comes from fill, space and the cell grid, not from drawn borders.

### Motion

- **Duration**: 320ms
- **Easing**: cubic-bezier(0.2, 0.7, 0.2, 1)
- **Character**: Cells light in sequence left to right when a reading settles, like a meter charging; reduced-motion shows the settled lit state instantly.

## Rules

### Composition

Compose pages as instrument panels: a calm top bar, a primary readout surface, and supporting meter and status modules arranged on a cell-aligned grid. Modules are flat dark-glass planes separated by generous space, never by borders or bevels.

### Hierarchy

Lead with one large screen title and tabular numerals for key readings; most hierarchy comes from the cell meters, the accent inks and the space between planes, not from heavy type or framing.

### Density

Information-rich but breathing: meters and readouts sit close enough to read together, with generous space around groups so the dark glass never feels crowded.

### Signature Patterns

- Render every quantity as a cell meter: a run of square cells where lit cells (in the state's accent ink) count the value and unlit cells are faint ghost squares on the ground.
- Colour-code state with three inks used like highlighters: amber for active, cyan for idle or informational, magenta for a peak or fault.
- Give lit cells a soft additive bloom so an active reading glows on the dark glass while idle readings stay quiet.
- Separate surfaces with space and a faint fill lift instead of borders or bevels, keeping corners square or softly rounded.
- Animate a settling reading by lighting its cells in sequence, left to right, like a meter charging.

## Layout

### Grid

A 12-column desktop grid on an 8px base unit, with an underlying square cell grid (typically 12–16px cells) that meters, readouts and module edges snap to so the whole panel reads cell-true.

### Breakpoints

At tablet widths, collapse the three-zone panel into two stacked rows while keeping full-width readouts and cell meters; at mobile widths, stack into a single column, let cell meters wrap their cells, and keep tables to their key columns.

### Whitespace

Space is the primary separator. Generous gaps frame each plane and each cell-meter group, so the dark glass reads as calm instrumentation rather than a crowded console.

### Breakpoints Map

- **Mobile**: 390px
- **Tablet**: 768px
- **Desktop**: 1200px
- **Wide**: 1600px

## Guidance

### Do

- Use the cell meter for every quantity — capacity, progress, signal, load — so readings stay discrete and on-brand.
- Map state to the three inks: amber active, cyan idle or info, magenta peak or fault.
- Keep the ground deep dark-glass so lit cells and accents read as emitted light.
- Separate surfaces with space and a faint fill lift, never with drawn borders or bevels.
- Use tabular monospace numerals so columns of figures align cell-true.

### Don't

- Do not smear scanlines, dither or noise across surfaces as nostalgia texture.
- Do not stamp embossed bevels or a single accent edge on panels and buttons.
- Do not replace cell meters with smooth gradient bars or glossy charts.
- Do not flood areas with magenta — it is a spark, never a field.
- Do not lighten the page toward white; the language is built for dark glass.

### Accessibility

Body text is 17px+ on a deep ground with warm off-white text for high contrast; cell meters never rely on colour alone — lit versus unlit count and a numeral readout carry the value too. Motion respects prefers-reduced-motion by showing the settled lit state instantly.

## Imagery Direction

### Pairs With

phosphene-cell-raster

### Summary

Imagery uses the Phosphene cell-raster technique: subjects are reconstructed from a strict grid of glowing square cells on dark glass, value carried by lit-cell density and a soft additive bloom, in the amber/cyan/magenta ink set.

### Subjects

- signal waveforms and readouts
- portraits and avatars in cells
- cityscapes and skylines
- single objects and still lifes
- landscapes and ridgelines

### Usage

Use full-bleed cell-raster fields for heroes with a sparse dark third for overlays; use centered single-subject cell renders for feature and avatar slots; keep empty-states near-dark with one faint cluster.

---
version: "alpha"
name: "Phosphene"
description: "Agent-curated design language exported from Katagami as DESIGN.md."
colors:
  primary: "#FFB72E"
  secondary: "#38E1D6"
  accent: "#FF4D8D"
  background: "#0B1020"
  surface: "#141A2E"
  text: "#F2EFE6"
  muted: "#8A93AD"
  border: "#222A42"
  on_accent: "#0B1020"
  error: "#FF5C6A"
  success: "#5BE3A0"
  warning: "#FFB72E"
  info: "#38E1D6"
typography:
  headline-lg:
    fontFamily: "Space Grotesk, sans-serif"
    fontSize: "2.075rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.01em"
  headline-md:
    fontFamily: "Space Grotesk, sans-serif"
    fontSize: "1.66rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.01em"
  body-md:
    fontFamily: "Inter, sans-serif"
    fontSize: "17px"
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: "-0.01em"
  label-md:
    fontFamily: "Space Mono, monospace"
    fontSize: "0.75rem"
    fontWeight: 600
    lineHeight: 1
    letterSpacing: "0.08em"
rounded:
  none: "0px"
  sm: "0px"
  md: "16px"
  lg: "16px"
  xl: "24px"
  full: "9999px"
spacing:
  base: "8px"
  xs: "4px"
  sm: "8px"
  md: "12px"
  lg: "16px"
  xl: "24px"
  2xl: "32px"
  3xl: "48px"
  4xl: "64px"
  step-8: "96px"
components:
  color-reference-primary:
    backgroundColor: "{colors.primary}"
  color-reference-secondary:
    backgroundColor: "{colors.secondary}"
  color-reference-accent:
    backgroundColor: "{colors.accent}"
  color-reference-background:
    backgroundColor: "{colors.background}"
  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-on_accent:
    backgroundColor: "{colors.on_accent}"
  color-reference-error:
    backgroundColor: "{colors.error}"
  color-reference-success:
    backgroundColor: "{colors.success}"
  color-reference-warning:
    backgroundColor: "{colors.warning}"
  color-reference-info:
    backgroundColor: "{colors.info}"
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#000000"
    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"
---

# Phosphene

## Overview

Phosphene reads the screen as a field of discrete glowing cells. Its one ownable idea is the cell meter: every quantity — capacity, signal, progress, load — is drawn as a run of lit and unlit square cells, and the colour of those cells carries operational state. Forms are built by counting light, not by smoothing it. The result is an instrument-panel language that stays calm and legible on a deep dark-glass ground, where a few bright inks behave like highlighters on glass.

### Values

- Quantize value: show amounts as counted cells, not smooth bars, so every reading is discrete and machine-honest.
- Let colour carry state: amber is active, cyan is idle or informational, magenta is a peak or a fault.
- Stay on dark glass: the deep ground makes lit cells and accents read as emitted light.
- Build hierarchy from light and space, not from boxes and edges.
- Keep it usable, not a costume: an instrument you would actually read, not retro decoration.

### Anti-Values

- Scanline and dither texture smeared across every surface as nostalgia wallpaper.
- Embossed dual-edge bevels stamped on every panel and button until they are noise.
- Smooth gradient meters and glossy charts that hide the discrete reading.
- Grey card borders and a single accent edge framing every module.
- Defaulting to a white page; this language lives on dark glass.

### Visual Character

- The cell meter is everywhere: capacities, progress, signal and load all render as rows or grids of square cells, lit cells in the accent ink and unlit cells as faint ghost squares on the ground.
- Lit cells carry a soft additive bloom, so an active reading glows against the dark glass like phosphor while an idle one sits quiet.
- Type is a clean technical sans for body and labels with a tabular monospace for numerals and readouts, so columns of figures line up cell-true.
- Status is told in three inks — amber active, cyan idle or info, magenta peak or fault — used like highlighters, never as fills.
- Surfaces are flat dark-glass planes separated by space and a faint lift, not by borders or bevels; corners are square or softly rounded, never pill-shaped.

## Colors

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

| Token | Value |
|-------|-------|
| primary | `#FFB72E` |
| secondary | `#38E1D6` |
| accent | `#FF4D8D` |
| background | `#0B1020` |
| surface | `#141A2E` |
| text | `#F2EFE6` |
| muted | `#8A93AD` |
| border | `#222A42` |
| on_accent | `#0B1020` |
| error | `#FF5C6A` |
| success | `#5BE3A0` |
| warning | `#FFB72E` |
| info | `#38E1D6` |

## Typography

- **Headline-Lg**: Space Grotesk, sans-serif, 2.075rem, weight 700, line-height 1.1.
- **Headline-Md**: Space Grotesk, sans-serif, 1.66rem, weight 600, line-height 1.15.
- **Body-Md**: Inter, sans-serif, 17px, weight 400, line-height 1.5.
- **Label-Md**: Space Mono, monospace, 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**: `96px`

### Grid

A 12-column desktop grid on an 8px base unit, with an underlying square cell grid (typically 12–16px cells) that meters, readouts and module edges snap to so the whole panel reads cell-true.

### Breakpoints

At tablet widths, collapse the three-zone panel into two stacked rows while keeping full-width readouts and cell meters; at mobile widths, stack into a single column, let cell meters wrap their cells, and keep tables to their key columns.

### Whitespace

Space is the primary separator. Generous gaps frame each plane and each cell-meter group, so the dark glass reads as calm instrumentation rather than a crowded console.

### Breakpoints Map

- **Mobile**: 390px
- **Tablet**: 768px
- **Desktop**: 1200px
- **Wide**: 1600px

## Elevation & Depth

### Shadows

- **Sm**: 0 0 0 transparent
- **Md**: 0 8px 24px rgba(0,0,0,0.45)
- **Lg**: 0 16px 48px rgba(0,0,0,0.55)
- **Glow**: 0 0 18px rgba(255,183,46,0.35)

## Shapes

### Rounded

- **None**: `0px`
- **Sm**: `0px`
- **Md**: `16px`
- **Lg**: `16px`
- **Xl**: `24px`
- **Full**: `9999px`

### Surfaces

- **Treatment**: flat
- **Card Style**: Flat dark-glass planes lifted from the ground by a hair of fill and a soft shadow; no borders, no bevels.
- **Bg Pattern**: cell-grid

### Borders

- **Default Width**: 0px
- **Accent Width**: 0px
- **Style**: none
- **Character**: Hierarchy comes from fill, space and the cell grid, not from drawn borders.

## Components

### Composition

Compose pages as instrument panels: a calm top bar, a primary readout surface, and supporting meter and status modules arranged on a cell-aligned grid. Modules are flat dark-glass planes separated by generous space, never by borders or bevels.

### Hierarchy

Lead with one large screen title and tabular numerals for key readings; most hierarchy comes from the cell meters, the accent inks and the space between planes, not from heavy type or framing.

### Density

Information-rich but breathing: meters and readouts sit close enough to read together, with generous space around groups so the dark glass never feels crowded.

### Signature Patterns

- Render every quantity as a cell meter: a run of square cells where lit cells (in the state's accent ink) count the value and unlit cells are faint ghost squares on the ground.
- Colour-code state with three inks used like highlighters: amber for active, cyan for idle or informational, magenta for a peak or fault.
- Give lit cells a soft additive bloom so an active reading glows on the dark glass while idle readings stay quiet.
- Separate surfaces with space and a faint fill lift instead of borders or bevels, keeping corners square or softly rounded.
- Animate a settling reading by lighting its cells in sequence, left to right, like a meter charging.

## 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-019efd24-4a9f-7d52-a054-c0c8695f5cfe/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 the cell meter for every quantity — capacity, progress, signal, load — so readings stay discrete and on-brand.
- Do Map state to the three inks: amber active, cyan idle or info, magenta peak or fault.
- Do Keep the ground deep dark-glass so lit cells and accents read as emitted light.
- Do Separate surfaces with space and a faint fill lift, never with drawn borders or bevels.
- Do Use tabular monospace numerals so columns of figures align cell-true.
- Don't Do not smear scanlines, dither or noise across surfaces as nostalgia texture.
- Don't Do not stamp embossed bevels or a single accent edge on panels and buttons.
- Don't Do not replace cell meters with smooth gradient bars or glossy charts.
- Don't Do not flood areas with magenta — it is a spark, never a field.
- Don't Do not lighten the page toward white; the language is built for dark glass.

### Accessibility

Body text is 17px+ on a deep ground with warm off-white text for high contrast; cell meters never rely on colour alone — lit versus unlit count and a numeral readout carry the value too. Motion respects prefers-reduced-motion by showing the settled lit state instantly.

## Imagery Direction

### Pairs With

phosphene-cell-raster

### Summary

Imagery uses the Phosphene cell-raster technique: subjects are reconstructed from a strict grid of glowing square cells on dark glass, value carried by lit-cell density and a soft additive bloom, in the amber/cyan/magenta ink set.

### Subjects

- signal waveforms and readouts
- portraits and avatars in cells
- cityscapes and skylines
- single objects and still lifes
- landscapes and ridgelines

### Usage

Use full-bleed cell-raster fields for heroes with a sparse dark third for overlays; use centered single-subject cell renders for feature and avatar slots; keep empty-states near-dark with one faint cluster.

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "phosphene",
  "type": "registry:theme",
  "title": "Phosphene shadcn Theme",
  "cssVars": {
    "theme": {},
    "light": {
      "background": "#0B1020",
      "foreground": "#F2EFE6",
      "card": "#141A2E",
      "card-foreground": "#F2EFE6",
      "popover": "#141A2E",
      "popover-foreground": "#F2EFE6",
      "primary": "#FFB72E",
      "primary-foreground": "#111111",
      "secondary": "#38E1D6",
      "secondary-foreground": "#111111",
      "muted": "#8A93AD",
      "muted-foreground": "#F2EFE6",
      "accent": "#FF4D8D",
      "accent-foreground": "#ffffff",
      "destructive": "#FF5C6A",
      "border": "#222A42",
      "input": "#222A42",
      "ring": "#FF4D8D",
      "chart-1": "#FFB72E",
      "chart-2": "#38E1D6",
      "chart-3": "#FF4D8D",
      "chart-4": "#5BE3A0",
      "chart-5": "#FFB72E",
      "sidebar": "#141A2E",
      "sidebar-foreground": "#F2EFE6",
      "sidebar-primary": "#FFB72E",
      "sidebar-primary-foreground": "#111111",
      "sidebar-accent": "#38E1D6",
      "sidebar-accent-foreground": "#111111",
      "sidebar-border": "#222A42",
      "sidebar-ring": "#FF4D8D",
      "radius": "16px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#FFB72E",
      "primary-foreground": "#111111",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#FF4D8D",
      "accent-foreground": "#ffffff",
      "destructive": "#FF5C6A",
      "border": "#303642",
      "input": "#303642",
      "ring": "#FF4D8D",
      "chart-1": "#FFB72E",
      "chart-2": "#38E1D6",
      "chart-3": "#FF4D8D",
      "chart-4": "#5BE3A0",
      "chart-5": "#FFB72E",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#FFB72E",
      "sidebar-primary-foreground": "#111111",
      "sidebar-accent": "#FF4D8D",
      "sidebar-accent-foreground": "#ffffff",
      "sidebar-border": "#303642",
      "sidebar-ring": "#FF4D8D",
      "radius": "16px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-019efd24-4a9f-7d52-a054-c0c8695f5cfe",
    "slug": "phosphene",
    "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",
        "background",
        "border",
        "error",
        "info",
        "muted",
        "on_accent",
        "primary",
        "secondary",
        "success",
        "surface",
        "text",
        "warning"
      ],
      "typography": [
        "base_size",
        "body_font",
        "google_fonts_url",
        "heading_font",
        "heading_transform",
        "heading_weight",
        "letter_spacing",
        "line_height",
        "mono_font",
        "scale_ratio"
      ],
      "spacing": [
        "base",
        "scale"
      ],
      "radii": [
        "full",
        "lg",
        "md",
        "none",
        "sm",
        "xl"
      ],
      "shadows": [
        "glow",
        "lg",
        "md",
        "sm"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "borders": [
        "accent_width",
        "character",
        "default_width",
        "style"
      ],
      "motion": [
        "character",
        "duration",
        "easing"
      ]
    }
  }
}
```