Phosphene

# Phosphene

## Philosophy

Phosphene reads the screen as a field of discrete glowing cells. Its one ownable idea is the cell meter: every quantity is a run of square cells, the lit ones count the value and their ink says the state, amber working, cyan waiting, magenta a peak. The page spends its own budget in cells, three inks, two typefaces, one image and one script, and shows that budget as a readout of itself. Forms are built by counting light, not by smoothing it, on a deep navy glass that is never lightened toward white.

### Values

- Quantize value: show amounts as counted cells, not smooth bars.
- Let colour carry state: amber working, cyan waiting, magenta a peak.
- Stay on dark glass so lit cells read as emitted light.
- Hierarchy from fill and space, with no borders, no gradients and no veil over the picture.
- Describe yourself honestly: a page may read out its own budget, never invented ops numbers.

### Anti-Values

- Hero veils, gradient bands and dot-gradient wallpaper.
- Nav bars of tiny links, tracked uppercase eyebrows and 01 / 02 / 03 step numerals.
- Traffic-light green, amber and red semantics.
- Glow on every cell; bloom belongs to the lit cells of a plate.
- Defaulting to a white page.

### Visual Character

- A full-bleed cell-raster lighthouse at full strength, with the type in its calm half.
- Cell meters of 14px squares, ghost cells in a faint blue grey, lit cells in one ink.
- Lexend at 600 to 700 with tight tracking for display and body; Datatype for numerals and readouts.
- Flat navy planes at radius 16 and 24, a pill for the one action, a 6px glyph of cells as the mark.

## Tokens

### Colors

| Name | Value |
|------|-------|
| bg | `#0B1020` |
| surface | `#141A2E` |
| text | `#F2EFE6` |
| muted | `#9AA3BD` |
| border | `#222A42` |
| accent | `#FFB72E` |
| accent_2 | `#38E1D6` |
| accent_3 | `#FF4D8D` |
| on_accent | `#0B1020` |
| ghost | `#2A3045` |
| success | `#8CF0D6` |
| warning | `#FFB72E` |
| error | `#FF6B8F` |
| info | `#38E1D6` |

### Typography

- **Heading Font**: Lexend, sans-serif
- **Body Font**: Lexend, sans-serif
- **Mono Font**: Datatype, monospace
- **Base Size**: 17px
- **Scale Ratio**: 1.2
- **Line Height**: 1.55
- **Letter Spacing**: -0.02em on display, -0.03em on the hero line, 0 on Datatype
- **Heading Weight**: 600
- **Heading Transform**: none
- **Google Fonts Url**: https://fonts.googleapis.com/css2?family=Datatype:wght@400..700&family=Lexend:wght@400;500;600;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 10px rgba(255,183,46,0.5)
- **Glow Cyan**: 0 0 10px rgba(56,225,214,0.5)
- **Glow Magenta**: 0 0 10px rgba(255,77,141,0.5)

### Surfaces

- **Treatment**: flat
- **Card Style**: Flat dark-glass planes lifted from the ground by a fill step (#141A2E on #0B1020); no borders, no gradients, no veil over the hero.
- **Bg Pattern**: none; the ground is flat navy. Cells are the only pattern.

### Borders

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

### Motion

- **Duration**: 250ms
- **Easing**: ease
- **Stagger**: 90ms per cell
- **Character**: With script and motion allowed, the plate charges its cells left to right once it scrolls into view. Without either, every cell lands lit.

## Rules

### Composition

- Open with a full-bleed cell-raster hero painted with var(--hero-image), the headline, one sentence and one pill action in its calm half, and no veil over the picture.
- Follow with the mechanic (what each ink means), a plate that reads the page's own budget in cell meters, a short note on how it reads, and a closing band with the one action.
- Planes are flat navy surfaces separated by 22px gaps and 96px between sections, never by borders.

### Hierarchy

- Lexend 600 for titles at -0.02em, 700 for the hero line; Datatype tabular numerals for every figure.
- One big numeral per plate; meters carry the rest.
- Prose is 17px or larger, in off-white for the fact and cool grey for the lede.

### Density

Calm instrument density: three cards across, one plate, 96px between sections, meter rows at 18px apart with generous glow-free space.

### Signature Patterns

- Cell meter: a run of 14px square cells; lit cells in the state ink count the value, ghost cells are faint squares on the surface.
- Three inks as highlighters: amber is working, cyan is waiting, magenta is a peak, one magenta cell at a time.
- Bloom only on the lit cells of the plate, a 10px glow in the cell's own ink.
- Self readout: the plate reads this page's own budget (3 inks, 2 typefaces, 1 image, 1 script) instead of invented ops figures.
- Charge in sequence: cells light left to right at 90ms steps once, only with script and motion allowed; the settled page is already lit.

## Layout

### Grid

A 1180px centred column with 24px gutters; three-up cards and a two-column plate (1fr to 1.2fr) on desktop; the hero spans the viewport and its content sits in the same column.

### Breakpoints

Under 1100px the hero image drops to the foot of the hero at full width with the type above it; under 920px cards and the plate stack to one column; under 600px a meter row puts its cells on their own line.

### Whitespace

96px above each section, 22px between cards, 40px inside the plate, 28 to 72px inside planes. Space and fill do the separating.

### Breakpoints Map

- **Mobile**: 390px
- **Tablet**: 834px
- **Desktop**: 1280px
- **Wide**: 2560px

### Responsive

Text is clamped (body 17px floor); the hero is capped to a centred 1180px column above 1440px while the image stays full bleed.

## Guidance

### Do

- Draw every quantity as a cell meter and say the number beside it.
- Map state to the three inks: amber working, cyan waiting, magenta a peak or fault.
- Keep the ground flat navy and let the hero image show at full strength with the type in its calm half.
- Separate planes with space and fill, never borders, gradients or a veil.
- Set figures in Datatype so columns align.

### Don't

- No hero veil, gradient band, nav bar, tracked eyebrow or numbered steps.
- No traffic-light semantics: success is mint-cyan, error is pink.
- Do not glow every cell; bloom lives on the lit cells of the plate.
- Do not flood anything with magenta; it is one spark.
- Do not lighten the page toward white.

### Accessibility

Body is 17px or larger on a deep ground with warm off-white text. Meters never rely on colour alone: the lit count and a numeral beside it carry the value. The settled state renders with no script, and prefers-reduced-motion shows every cell lit with no transition.

## Imagery Direction

### Pairs With

phosphene-cell-raster

### Summary

The Phosphene cell-raster technique: subjects rebuilt from a strict grid of glowing square cells on dark glass, value carried by lit-cell density, in amber, cyan and magenta. The live hero is a lighthouse whose calm left half is plain ground, with the stray cells cleared so type sits on it.

### Subjects

- a lighthouse on a ridge
- signal waveforms and readouts
- cityscapes and skylines
- single objects and still lifes
- landscapes and ridgelines

### Usage

One full-bleed cell-raster hero, painted with var(--hero-image), the subject on the right and the left third plain dark for type, with no veil. On tablets and phones the image sits at the foot of the hero at full width. Inside pages carry no illustration; the cells are the picture.

---
version: "alpha"
name: "Phosphene"
description: "Phosphene reads the screen as a field of discrete glowing cells. Its one ownable idea is the cell meter: every quantity is a run of square cells, the lit ones count the value and their ink says the state, amber working, cyan waiting, mag..."
colors:
  bg: "#0B1020"
  surface: "#141A2E"
  text: "#F2EFE6"
  muted: "#9AA3BD"
  border: "#222A42"
  accent: "#FFB72E"
  accent_2: "#38E1D6"
  accent_3: "#FF4D8D"
  on_accent: "#0B1020"
  ghost: "#2A3045"
  success: "#8CF0D6"
  warning: "#FFB72E"
  error: "#FF6B8F"
  info: "#38E1D6"
typography:
  headline-lg:
    fontFamily: "Lexend, sans-serif"
    fontSize: "2.075rem"
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  headline-md:
    fontFamily: "Lexend, sans-serif"
    fontSize: "1.66rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: "Lexend, sans-serif"
    fontSize: "17px"
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: "-0.02em"
  label-md:
    fontFamily: "Datatype, 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-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-ghost:
    backgroundColor: "{colors.ghost}"
  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: "{colors.on_accent}"
    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 is a run of square cells, the lit ones count the value and their ink says the state, amber working, cyan waiting, magenta a peak. The page spends its own budget in cells, three inks, two typefaces, one image and one script, and shows that budget as a readout of itself. Forms are built by counting light, not by smoothing it, on a deep navy glass that is never lightened toward white.

### Values

- Quantize value: show amounts as counted cells, not smooth bars.
- Let colour carry state: amber working, cyan waiting, magenta a peak.
- Stay on dark glass so lit cells read as emitted light.
- Hierarchy from fill and space, with no borders, no gradients and no veil over the picture.
- Describe yourself honestly: a page may read out its own budget, never invented ops numbers.

### Anti-Values

- Hero veils, gradient bands and dot-gradient wallpaper.
- Nav bars of tiny links, tracked uppercase eyebrows and 01 / 02 / 03 step numerals.
- Traffic-light green, amber and red semantics.
- Glow on every cell; bloom belongs to the lit cells of a plate.
- Defaulting to a white page.

### Visual Character

- A full-bleed cell-raster lighthouse at full strength, with the type in its calm half.
- Cell meters of 14px squares, ghost cells in a faint blue grey, lit cells in one ink.
- Lexend at 600 to 700 with tight tracking for display and body; Datatype for numerals and readouts.
- Flat navy planes at radius 16 and 24, a pill for the one action, a 6px glyph of cells as the mark.

## 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 | `#0B1020` |
| surface | `#141A2E` |
| text | `#F2EFE6` |
| muted | `#9AA3BD` |
| border | `#222A42` |
| accent | `#FFB72E` |
| accent_2 | `#38E1D6` |
| accent_3 | `#FF4D8D` |
| on_accent | `#0B1020` |
| ghost | `#2A3045` |
| success | `#8CF0D6` |
| warning | `#FFB72E` |
| error | `#FF6B8F` |
| info | `#38E1D6` |

## Typography

Load the fonts from Google Fonts: https://fonts.googleapis.com/css2?family=Datatype:wght@400..700&family=Lexend:wght@400;500;600;700&display=swap

- **Headline-Lg**: Lexend, sans-serif, 2.075rem, weight 700, line-height 1.1.
- **Headline-Md**: Lexend, sans-serif, 1.66rem, weight 600, line-height 1.15.
- **Body-Md**: Lexend, sans-serif, 17px, weight 400, line-height 1.5.
- **Label-Md**: Datatype, 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 1180px centred column with 24px gutters; three-up cards and a two-column plate (1fr to 1.2fr) on desktop; the hero spans the viewport and its content sits in the same column.

### Breakpoints

Under 1100px the hero image drops to the foot of the hero at full width with the type above it; under 920px cards and the plate stack to one column; under 600px a meter row puts its cells on their own line.

### Whitespace

96px above each section, 22px between cards, 40px inside the plate, 28 to 72px inside planes. Space and fill do the separating.

### Breakpoints Map

- **Mobile**: 390px
- **Tablet**: 834px
- **Desktop**: 1280px
- **Wide**: 2560px

### Responsive

Text is clamped (body 17px floor); the hero is capped to a centred 1180px column above 1440px while the image stays full bleed.

## 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 10px rgba(255,183,46,0.5)
- **Glow Cyan**: 0 0 10px rgba(56,225,214,0.5)
- **Glow Magenta**: 0 0 10px rgba(255,77,141,0.5)

## 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 fill step (#141A2E on #0B1020); no borders, no gradients, no veil over the hero.
- **Bg Pattern**: none; the ground is flat navy. Cells are the only pattern.

### Borders

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

## Components

### Composition

- Open with a full-bleed cell-raster hero painted with var(--hero-image), the headline, one sentence and one pill action in its calm half, and no veil over the picture.
- Follow with the mechanic (what each ink means), a plate that reads the page's own budget in cell meters, a short note on how it reads, and a closing band with the one action.
- Planes are flat navy surfaces separated by 22px gaps and 96px between sections, never by borders.

### Hierarchy

- Lexend 600 for titles at -0.02em, 700 for the hero line; Datatype tabular numerals for every figure.
- One big numeral per plate; meters carry the rest.
- Prose is 17px or larger, in off-white for the fact and cool grey for the lede.

### Density

Calm instrument density: three cards across, one plate, 96px between sections, meter rows at 18px apart with generous glow-free space.

### Signature Patterns

- Cell meter: a run of 14px square cells; lit cells in the state ink count the value, ghost cells are faint squares on the surface.
- Three inks as highlighters: amber is working, cyan is waiting, magenta is a peak, one magenta cell at a time.
- Bloom only on the lit cells of the plate, a 10px glow in the cell's own ink.
- Self readout: the plate reads this page's own budget (3 inks, 2 typefaces, 1 image, 1 script) instead of invented ops figures.
- Charge in sequence: cells light left to right at 90ms steps once, only with script and motion allowed; the settled page is already lit.

## 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-01a117ce-d8f0-72e0-9ca0-c47c3b30f006/DESIGN.with-shadcn.md`.

Machine-readable companions for automation: `/language/en-01a117ce-d8f0-72e0-9ca0-c47c3b30f006/shadcn.json` (registry theme), `/language/en-01a117ce-d8f0-72e0-9ca0-c47c3b30f006/shadcn-components.md` (component recipes) and `/language/en-01a117ce-d8f0-72e0-9ca0-c47c3b30f006/shadcn-shots.json` (preview shots). The human-facing handoff is still 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 Draw every quantity as a cell meter and say the number beside it.
- Do Map state to the three inks: amber working, cyan waiting, magenta a peak or fault.
- Do Keep the ground flat navy and let the hero image show at full strength with the type in its calm half.
- Do Separate planes with space and fill, never borders, gradients or a veil.
- Do Set figures in Datatype so columns align.
- Don't No hero veil, gradient band, nav bar, tracked eyebrow or numbered steps.
- Don't No traffic-light semantics: success is mint-cyan, error is pink.
- Don't Do not glow every cell; bloom lives on the lit cells of the plate.
- Don't Do not flood anything with magenta; it is one spark.
- Don't Do not lighten the page toward white.

### Accessibility

Body is 17px or larger on a deep ground with warm off-white text. Meters never rely on colour alone: the lit count and a numeral beside it carry the value. The settled state renders with no script, and prefers-reduced-motion shows every cell lit with no transition.

## Imagery Direction

### Pairs With

phosphene-cell-raster

### Summary

The Phosphene cell-raster technique: subjects rebuilt from a strict grid of glowing square cells on dark glass, value carried by lit-cell density, in amber, cyan and magenta. The live hero is a lighthouse whose calm left half is plain ground, with the stray cells cleared so type sits on it.

### Subjects

- a lighthouse on a ridge
- signal waveforms and readouts
- cityscapes and skylines
- single objects and still lifes
- landscapes and ridgelines

### Usage

One full-bleed cell-raster hero, painted with var(--hero-image), the subject on the right and the left third plain dark for type, with no veil. On tablets and phones the image sits at the foot of the hero at full width. Inside pages carry no illustration; the cells are the picture.

```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": "#F2EFE6",
      "primary-foreground": "#111111",
      "secondary": "#f4f4f5",
      "secondary-foreground": "#111111",
      "muted": "#9AA3BD",
      "muted-foreground": "#F2EFE6",
      "accent": "#FFB72E",
      "accent-foreground": "#111111",
      "destructive": "#FF6B8F",
      "border": "#222A42",
      "input": "#222A42",
      "ring": "#FFB72E",
      "chart-1": "#F2EFE6",
      "chart-2": "#f4f4f5",
      "chart-3": "#FFB72E",
      "chart-4": "#8CF0D6",
      "chart-5": "#FFB72E",
      "sidebar": "#141A2E",
      "sidebar-foreground": "#F2EFE6",
      "sidebar-primary": "#F2EFE6",
      "sidebar-primary-foreground": "#111111",
      "sidebar-accent": "#38E1D6",
      "sidebar-accent-foreground": "#111111",
      "sidebar-border": "#222A42",
      "sidebar-ring": "#FFB72E",
      "radius": "16px"
    },
    "dark": {
      "background": "#0f1115",
      "foreground": "#f8fafc",
      "card": "#181b22",
      "card-foreground": "#f8fafc",
      "popover": "#181b22",
      "popover-foreground": "#f8fafc",
      "primary": "#F2EFE6",
      "primary-foreground": "#111111",
      "secondary": "#252a33",
      "secondary-foreground": "#f8fafc",
      "muted": "#252a33",
      "muted-foreground": "#a1a1aa",
      "accent": "#FFB72E",
      "accent-foreground": "#111111",
      "destructive": "#FF6B8F",
      "border": "#303642",
      "input": "#303642",
      "ring": "#FFB72E",
      "chart-1": "#F2EFE6",
      "chart-2": "#f4f4f5",
      "chart-3": "#FFB72E",
      "chart-4": "#8CF0D6",
      "chart-5": "#FFB72E",
      "sidebar": "#181b22",
      "sidebar-foreground": "#f8fafc",
      "sidebar-primary": "#F2EFE6",
      "sidebar-primary-foreground": "#111111",
      "sidebar-accent": "#FFB72E",
      "sidebar-accent-foreground": "#111111",
      "sidebar-border": "#303642",
      "sidebar-ring": "#FFB72E",
      "radius": "16px"
    }
  },
  "meta": {
    "source": "katagami",
    "languageId": "en-01a117ce-d8f0-72e0-9ca0-c47c3b30f006",
    "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",
        "accent_2",
        "accent_3",
        "bg",
        "border",
        "error",
        "ghost",
        "info",
        "muted",
        "on_accent",
        "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",
        "glow_cyan",
        "glow_magenta",
        "lg",
        "md",
        "sm"
      ],
      "surfaces": [
        "bg_pattern",
        "card_style",
        "treatment"
      ],
      "borders": [
        "accent_width",
        "character",
        "default_width",
        "style"
      ],
      "motion": [
        "character",
        "duration",
        "easing",
        "stagger"
      ]
    }
  }
}
```