# Kotomin Design System

Monochrome liquid-chrome identity for **Kotomin** — a Linux/embedded engineer and reverse
engineer. Black-ground poster system: four-point sparkles, hairline frames with corner ticks,
chrome spheres, high-contrast italic display type and dense mono spec captions. Underground,
technical, celestial — never corporate, never playful.

The whole system derives from one artifact: a sharp italic wordmark with flame-like spikes and
long horizontal speed strokes, existing in two texture modes — clean vector, and coarse halftone
dither.

---

## Sources given

| Source | What it is |
| --- | --- |
| `uploads/Kotomin.svg` | Clean vector wordmark, 623.89 × 207.28. **The authoritative master.** |
| `uploads/Kotomin_Pdf.pdf` | Same lockup, single page, pure vector (no embedded fonts). |
| `uploads/Logo.png` | Raster wordmark, black on transparent, 269 × 156. |
| `uploads/Logo-2.jpg` | Wordmark, coarse halftone dither, black on white. |
| `uploads/Logo-4.jpg` | Wordmark, coarse halftone dither, **inverted** (white on black). |
| `uploads/Logo-1.jpg`, `uploads/Logo-3.jpg` | Isolated dithered crops of the speed-line strokes. |

No codebase, Figma file, deck, or product screenshots were provided, and no font binaries.
Everything below the identity layer (tokens, components, the UI kit) is derived from the logo
assets and the written brief, not from an existing product. Where that required a decision it is
called out under **Substitutions & assumptions**.

---

## Content fundamentals

**Voice.** Quiet, exact, unhurried. The brand’s authority comes from restraint: one object on the
screen, one line of copy under it, and nothing that is not doing work. Do **not** frame Kotomin in
trade jargon (kernels, firmware, reverse engineering) — the identity is about the object and its
finish, not a job description. Technical detail belongs in a figure caption or a terminal block, and
only when the reader asked for it.

- **Casing.** Display and label type is **UPPERCASE** (set in CSS, not typed that way).
  Running prose is **sentence case**. Technical nouns stay **lowercase** always: `rust`, `ghidra`,
  `aarch64`, `v4l2`, `~/rk3588`. Never title-case a command, tag, or filename.
- **Person.** First person singular for the engineer's own work — *"I make silicon admit what it
  does"*, *"I will send a one-page mutual NDA"*. Second person for instructions to the reader —
  *"Start where the hardware cannot lie"*. Never "we" (there is no we) and never third person.
- **Length.** Headlines 2–5 words. Body sentences under 25 words. Labels 1–3 words. A void screen
  gets **one** sentence in total. Button labels are imperative verbs with no punctuation: `send`,
  `next`, `close`, `hire`.
- **Numbers are the argument.** Prefer `214 registers, zero docs` to "extensive analysis";
  `built in 41s` to "fast builds"; `1841 insertions(+)` to "a substantial patch".
- **No exclamation marks. No emoji. No em-dash enthusiasm. No marketing verbs**
  ("empower", "unlock", "seamless", "revolutionise"). No "Let's".
- **Negative space is voice too.** `no recruiters`, `filtered at the mta`, `public work only.
  Contract teardowns are under NDA and are not listed.` Saying what is refused is on-brand.
- **Status reads like a log line.** `ok flashed · 12.4 mb in 3.1 s`, `err warning: vendor blob
  mismatch, ignoring`. Lowercase, mono, timestamped, no apology and no cheer.

Copy examples, verbatim from the kit:

> Built to be looked at closely.
> Made to be looked at.
> A small practice. Objects and interfaces, finished properly, in black and white.
> Fewer things, further apart.
> Six objects. Each one finished.
> One address. No forms to fill twice.

---

## Visual foundations

### Colour
Strictly monochrome — **there is no colour in this system, and no coloured accent.** The ground is
true black (`--black-900: #000000`); `--ink: #231F20` remains the logo's own black for print.
Surfaces are not filled greys but **near-transparent whites** (`--surface-card:
rgba(255,255,255,0.02)`) and hairlines are alpha whites (`--border-hairline:
rgba(255,255,255,0.16)`) so everything floats on the black rather than sitting in boxes.

One accent — silver — and **it is never a CSS gradient.** `--chrome-100…500` is a flat ramp for
hairlines, tints and small fills, and that is all CSS gets. **Chrome as a material exists only as
real 3D** (`ChromeMark3D`, `ChromeFilament`), which build their own specular environment in a
shader. A gradient standing in for metal reads cheap at any size — do not reintroduce one.

`--signal` is pure white: focus rings, `::selection`, the switch on-state.

**One exception to the monochrome rule: the terminal.** `TerminalBlock` uses a phosphor palette
(`--term-green`, `--term-amber`, `--term-red`, `--term-cyan`, `--term-violet`) because there the
colour is *functional* — success, warning, error, path, annotation. It never leaves that component;
pass `mono` to drop it. Nothing else in the system may use a hue.
Semantic states are grayscale (`--state-danger` white, `--state-warn` white-400, `--state-ok`
chrome-200) — severity reads through weight, label text and position, never hue.

### Type
Three families, three jobs. No font binaries were supplied; all three are **substituted**
Google Fonts (flagged below).
- **Anybody** — `--font-hero`, the display voice. A techno-geometric italic with a variable width
  axis (50–150), which is what lets headline type sit on the same axis as the wordmark instead of
  reading as a classical serif. Every hero and page `h1` is set in it, italic, solid white via
  `.k-hero`. Widen it (`font-stretch: 110–125%`) at hero scale; condense it for secondary lines.
- **Archivo** — `--font-display` for heavy uppercase poster slabs (`h2`, `h3`) and
  `--font-body` for running copy at 15/1.55.
- **JetBrains Mono** — every label, spec caption, tag, timestamp and terminal line.

Two mono treatments carry the whole layout: the **11px uppercase label** at `+0.34em`
(`--type-label` / `.k-label`), and the **spaced rule label** at `+0.62em` (`--tracking-spaced` /
`.k-spaced`) that sits in a gap in a hairline — the `T H I S   I S` device from the reference
posters. Dense supporting detail is set as **11px justified mono in 2–4 columns**
(`--type-spec` / `SpecColumns`), never as one wide paragraph.

### Layout & spacing
4px grid, `--space-1…12` (2 → 192px). Sections use 96px vertical / 48px horizontal padding;
cards 24px; controls 8/16px. Content max width 1280px, prose 760px. Grids are asymmetric on
purpose (`1.1fr / 1fr`) — the identity is diagonal and off-axis, so perfect symmetry reads wrong.
The top bar is the only fixed/sticky element; it carries the marquee status band beneath it.

### Backgrounds & texture
The page is black and mostly empty. Texture arrives in named layers, never all at once:
1. **Stipple** — `--dither-50` / `--dither-25` dot grids at 0.3–0.5 opacity (the supplied dithered
   bitmaps are the print-scale version of the same idea).
2. **Wire grid** — `--wire-grid`, radially masked so it fades toward the top; the horizon device.
3. **Sparkle field** — `StarField`, corner clusters or a vertical rail.
4. **Strips** — `--checker` (10px checkerboard) and `--hatch` (72° slashes) as loud band breaks;
   **max two per screen**.
5. **Chrome** — one `ChromeOrb` as the section's focal object.

Isolated crops of the wordmark's strokes act as watermarks at 0.2–0.4 opacity. **No photography**
is specified; any imagery introduced must be monochrome and stippled. No gradients other than the
three chrome ones. No illustration, no glassmorphism.

### Borders, corners, shadows
**Radius is always 0 — with one exception: the perfect circle.** Orbs, and only orbs, are round.
Slanted edges lean on the wordmark's italic axis (`--clip-cut`, `--clip-shear`); a rounded corner
is a brand violation.

Borders are 1px alpha-white hairlines that rise to `--border-strong` on hover. Prefer **corner
ticks** (`FrameBox`) over a continuous border — they read lighter and are the poster system's
signature. **No soft drop shadows anywhere.** Depth comes from hairlines, chrome speculars,
stipple density and the real 3D objects. Text over texture is protected by a solid backing block,
never a blur or fade.

### Transparency & blur
Used sparingly and only for modal separation: the `Dialog` backdrop is ink at 82% with a dither
veil blended over it. `--blur-veil` exists for that case alone. No frosted panels, no translucent
navigation, no backdrop-filter on content surfaces.

### Motion
Slow and celestial, or instant — never bouncy. `130ms` linear for controls, `240ms` for larger
changes. **No bounce, no spring, no scale-on-hover, no cross-fade.** Four brand motions:
- **twinkle** — 3.6s opacity + scale pulse on sparkles, desynchronised across a cluster;
- **orbit** — 34s linear rotation of the chrome specular sweep;
- **marquee** — 70s constant-speed linear ticker (never below 40s; a fast ticker reads cheap);
- **stipple dissolve** — stepped opacity (`--ease-step`) rather than a smooth fade.

Everything honours `prefers-reduced-motion` (all animation stops via `tokens/base.css`).

### Interaction states
**Type is never animated.** No tracking, size or weight changes on hover — a label that re-tracks
reflows and reads cheap. Feedback is geometric and tonal instead: a 1px rule draws in under the
label, a sparkle fades in, the border rises, the colour brightens.

| State | Treatment |
| --- | --- |
| Hover, button / tab / nav | a 1px rule draws in under the label, colour brightens, sparkle fades in. Type is untouched, so nothing reflows or shifts |
| Hover, card / row | hairline rises to `--border-strong`, background lifts to `rgba(255,255,255,0.04)` |
| Press | `translateY(1px)` — a nudge, never a scale |
| Focus | 1px white outline at 3px offset |
| Disabled | transparent fill, 10%-alpha border, `--state-disabled-text` |
| Selected | white fill with black text, or a sparkle + hairline for tabs |

### Cards
Near-transparent blocks held by a hairline: `rgba(255,255,255,0.02)` fill, 1px alpha border, 24px
padding, **no radius, no shadow**. `figure` prefixes the eyebrow with a sparkle; `dither` adds the
stipple veil (feature cards only). For images, diagrams and figures use **`FrameBox`** instead —
corner ticks plus a `Nº 00x` figure label — not a filled card.

---

## Iconography

The brand's own ornament does most of the work icons usually would: the **four-point sparkle**
(`Star`), corner ticks, corner arrows (`↖ ↘`), figure numbers, checker and hatch strips, and the
wireframe orb. Reach for a UI icon only when an action genuinely needs one.

**No icon set was supplied** with the brand assets. **Substituted: [Lucide](https://lucide.dev)
0.469** from CDN (`https://unpkg.com/lucide@0.469.0/dist/umd/lucide.js`) for its 1.5px uniform
stroke and flat terminals. **Flagged for replacement** if a real set exists.

Rules:
- 16px at 1.5px stroke inside controls; 15px inline. Always `currentColor`.
- Line icons only — never filled, never duotone, never rounded-cap.
- Icons never appear without a label or `aria-label`; `IconButton` requires one.
- **Emoji are never used**, in UI or copy.
- Unicode glyphs are used deliberately as ornaments: `$` prompt, `→ ←` arrows, `↖ ↘` frame
  corners, `▼` select caret, `×` dismiss, `·` separator, `Nº` figure prefix.
- Sparkles are **decorative only** — a star never carries meaning on its own.

### Assets shipped
| File | Use |
| --- | --- |
| `assets/logo-kotomin.svg` | **Master** clean wordmark, `fill: currentColor` (mask or inline use) |
| `assets/logo-kotomin-white.svg` | White-filled master, for plain `<img>` on dark |
| `assets/logo-kotomin.png` | Raster black wordmark, transparent |
| `assets/logo-kotomin.pdf` | Vector wordmark for print |
| `assets/mark-speedline.svg` | Wordmark **minus its letters** — standalone mark, `currentColor` |
| `assets/mark-speedline-white.svg` | White-filled mark for `<img>` |
| `assets/logo-dither.jpg` | Halftone wordmark, black on white |
| `assets/logo-dither-inverted.jpg` | Halftone wordmark, white on black — the hero variant |
| `assets/speedline-dither-a.jpg`, `-b.jpg` | Isolated dithered stroke crops for backgrounds |

Logo rules: **the mark wants to be large.** On any hero or landing surface it should occupy
**60–85% of the viewport width** and be sized in viewport units, not pixels, so it holds up on a 27"
or 32" display — use `ChromeMark3D`, or `Wordmark` with a `vw`-based height. Never a fixed 40px
lockup floating in empty space. Minimum height is 18px for the full lockup in navigation chrome and
80px for any dither variant. Clear space = the wordmark's cap-height on all sides. Never outline,
rotate, re-space, recolour, or re-type the name as a substitute for the mark.

---

## Substitutions & assumptions

1. **Fonts are substituted.** No binaries were provided. Anybody (hero serif) + Archivo
   (display slabs and body) + JetBrains Mono are Google Fonts stand-ins. **Please send the real font files** (or name the licensed families) and the swap is a
   one-file change in `tokens/fonts.css`.
2. **Icons are substituted** (Lucide 0.469, CDN) — see Iconography.
3. **Strictly monochrome by request** (2026-07 revision): the acid-lime accent was removed; chrome
   is the only accent and all semantic states are grayscale. A second revision replaced the boxy
   "terminal" register with the black-ground poster system — sparkles, corner-tick frames, chrome
   orbs, spaced rule labels — derived from the three mood-board references the user supplied.
4. **No product UI existed**, so `ui_kits/site/` is an *application* of the identity to a plausible
   surface (the engineer's own site), not a recreation. Its information architecture is a proposal;
   its visual foundations are authoritative.
5. **Component inventory** — no source defined one, so the standard primitive set was authored.
   *Intentional additions* beyond the standard set, each carrying one device of the poster system:
   `Wordmark` (single source of the mark), `Star` + `StarField` (the four-point sparkle ornament),
   `ChromeMark3D` (the mark extruded into rotatable chrome — the hero object), `EdgeLabel`
   (viewport-edge micro-labels, the only text furniture a void layout gets),
   `ChromeFilament` (a real 3D chrome filament that draws itself in on scroll — the background
   object), `FrameBox` (corner-tick frame with figure numbers),
   `StripRule` (checker / hatch / starred band breaks), `SpecColumns` (the mono caption
   wall), `DitherPanel` (the textured hero surface),
   `TerminalBlock` (the brand shows commands instead of prose), `Marquee` (slow sparkle ticker),
   `Divider` (the spaced-label section opener).

---

## Index

**Root**
- `styles.css` — the single entry point consumers link. `@import` lines only.
- `thumbnail.html` — homepage tile.
- `readme.md` — this file. `SKILL.md` — Agent Skills wrapper.

**`tokens/`** — `fonts.css`, `colors.css`, `typography.css`, `spacing.css`, `borders.css`,
`effects.css`, `motion.css`, `base.css` (resets + `.k-label` / `.k-dither` utilities).

**`assets/`** — logos, marks, dither variants (table above), plus two mood-board stipple
textures (`texture-nebula.png`, `texture-stipple-orb.png`) for hero backgrounds — user-supplied
reference imagery, license unverified.

**`guidelines/`** — 27 specimen cards feeding the Design System tab:
Colors (Ink & Paper, dark ramp, light ramp, chrome, accent policy) ·
Type (hero, display, headings, body, mono, labels, spec captions, scale) ·
Spacing (scale, card anatomy) ·
Brand (primary lockup, sparkle, chrome orb, frames, strips, ghost stack, dither variants,
speed lines, speed-line mark, texture modes, corners, states).

**`components/`** — 27 primitives, all exported on `window.KotominDesignSystem_70f2a9`:
| Group | Components |
| --- | --- |
| `core/` | `Button` `IconButton` `Card` `Badge` `Tag` `Divider` |
| `forms/` | `Input` `Select` `Checkbox` `Radio` `Switch` |
| `navigation/` | `Tabs` |
| `feedback/` | `Dialog` `Toast` `Tooltip` |
| `brand/` | `Wordmark` `ChromeMark3D` `ChromeFilament` `EdgeLabel` `Star` `StarField` `FrameBox` `StripRule` `SpecColumns` `DitherPanel` `TerminalBlock` `Marquee` |

Each directory has `<Name>.jsx`, `<Name>.d.ts`, `<Name>.prompt.md`, and one `*.card.html` demo.
Set `window.KOTOMIN_ASSET_BASE` to the relative path of `assets/` before mounting `Wordmark` or
`DitherPanel`.

**`ui_kits/void/`** — **the flagship surface.** One black screen; the wordmark itself, extruded
into liquid chrome in three.js and drag-rotatable, is the only object on it. Everything else is a
10px mono label pinned to a viewport edge (`index.html`, `VoidScreen.jsx`, `README.md`).

**`ui_kits/site/`** — the denser editorial counterpart: four-screen click-through of `kotomin.dev`
(`index.html`, `Shell.jsx`, `HomeScreen.jsx`, `WorkScreen.jsx`, `NoteScreen.jsx`,
`ContactScreen.jsx`, `README.md`).

**`templates/site-page/`** — `SitePage.dc.html`, a page scaffold (wordmark bar, marquee, dithered
hero, hairline sections, terminal figure, footer) that consuming projects can start from.

No slide template was supplied, so no sample slides were authored.