Hikari UI — foundational product spec (epic)

[pghqdev]

Foundational / epic spec. Captures the full Hikari UI product vision (migrated from idea.md). Too large to build cold in one pass — the first AFK-ready unit (CSS core + kitchen-sink page) should be carved out of this. Kept as one document so the vision lives in the tracker, not a loose file.

Problem Statement

Developers — increasingly AI coding agents driving the keyboard — need to ship UI that looks good. Today they reach for generic Tailwind and every result looks like the same "AI slop": models are excellent at semantic HTML but poor at consistent bespoke styling, so every freestyled utility class is a chance to produce mush. Existing CSS options force a bad trade: Pico/Water are tasteful but too minimal to build real UIs; DaisyUI/Bootstrap are capable but class-heavy and (DaisyUI) require Tailwind. There is no CSS-first, framework-agnostic library that makes bare semantic HTML look genuinely tasteful by default, themes beautifully, and is trivial for an agent to adopt correctly.

Solution

Hikari UI — a class-light CSS framework for semantic HTML. Bare tags look great out of the box; a small data-* vocabulary adds variants; a data-theme container swaps the whole palette — including depth and glow — from ~20 tokens. CSS does the work; a tiny optional JS helper (hikari.js) handles the few things CSS can't. It ships an agent-adoption layer (canonical rules → llms.txt / AGENTS.md / an installable Skill) so an agent told to "use Hikari" writes semantic HTML and inherits taste instead of freestyling slop.

Positioning: Minimalistic. Tasteful. Snappy. The wedge is taste-rails for the agentic coding era; the secondary differentiator is aesthetic + a drop-in theme ecosystem. The goal is credibility (HN / PH / X front page on aesthetics + theming), not usage-count dominance or beating Pico on bytes.

User Stories

1. As a developer, I want bare <button> to look great with no classes, so that I get taste without styling work.
2. As a developer, I want to add a variant with <button data-variant="solid">, so that I can express options without class soup.
3. As a developer, I want to drop one CDN <link> into any page, so that adoption is a single line.
4. As a developer, I want Hikari to work in React, Next, Svelte, Vue, Astro, and server-rendered templates, so that I'm not locked to a framework.
5. As a developer, I want my own CSS overrides to always win without !important, so that Hikari is a starting point, not a cage.
6. As a developer on a page I control, I want Hikari to style my semantic HTML, while accepting it deliberately yields to pre-existing site CSS.
7. As a developer, I want a bare page to respect the OS light/dark preference automatically, so that dark mode works with zero config.
8. As a developer, I want to force a specific theme via data-theme on a container, so that I can override the OS default per-section.
9. As a developer, I want nested data-theme containers to each apply their own palette, so that I can theme a region independently.
10. As a developer, I want a styled <dialog> that opens as a modal, so that I get a modern dialog without hand-rolling CSS.
11. As a developer, I want tabs that work with native state, so that I get a core interactive component at launch.
12. As a developer, I want accordion (<details>), dropdown, tooltip, card, badge, alert, and chip, so that I can build a real interface.
13. As a developer, I want an auto-dismiss toast, so that transient feedback works with a minimal JS sprinkle.
14. As a developer, I want a theme switcher with localStorage persistence, so that a user's theme choice survives reloads.
15. As a developer, I want a copy-paste inline no-FOUC snippet, so that a persisted theme doesn't flash on load.
16. As a developer who wants no extra file, I want every hikari.js helper documented as paste-it-yourself vanilla, so that the JS is optional.
17. As a developer, I want styled form-validation states (:user-invalid), so that forms communicate errors by default.
18. As an AI coding agent, I want a canonical rules file that tells me to write semantic HTML and forbids utility-class freestyling, so that I produce tasteful output instead of slop.
19. As an AI coding agent, I want an AGENTS.md I can read as project rules, so that I use Hikari correctly in a consuming repo.
20. As an AI coding agent / doc-fetcher, I want an llms.txt at the domain root, so that I can load a condensed doc map and rules.
21. As a Claude Code user, I want curl … | sh to install a Hikari Skill that triggers on UI work, so that the rules are actively enforced.
22. As a theme author, I want a theme to be ~20 tokens and nothing else, so that writing one takes minutes.
23. As a theme author, I want the accent/accent-content pairing to guarantee contrast, so that my theme can't ship unreadable text.
24. As a theme author, I want shipped themes (light, dark, nord, dracula, catppuccin, …), so that I have a starting library.
25. As a site visitor evaluating Hikari, I want a dense kitchen-sink page whose theme dropdown re-lights the whole page including shadows, so that I can see the value in one interaction.
26. As a site visitor, I want a token playground (drag accent hue / radius / space) that recomputes live, so that I understand it's all ~20 variables.
27. As a site visitor, I want a static screenshot of the defaults to look tasteful cold, so that I'm convinced without a demo.
28. As a user with prefers-reduced-motion, I want all transitions (including --ease-hikari) disabled, so that motion never harms me.
29. As a maintainer, I want a documented "what Hikari deliberately doesn't do" page, so that cut scope reads as principle, not gap.
30. As a maintainer, I want the framework authored in plain modern CSS partials bundled by one dev-dep (Lightning CSS), so that the shipped artifact stays runtime-dependency-free.
31. As a maintainer, I want the design language (quiet surface, rationed electric accent, one easing curve) applied uniformly, so that the product feels coherent even in a GIF.
32. As a maintainer, I want the doctrine communicated by product behavior rather than sermon, so that it reads as earned, not pretentious.

Implementation Decisions

• API model — class-light. Bare semantic tags are styled by default. Variants via native attributes + data-* (e.g. data-variant="solid"). Not classless (caps expressiveness), not class-heavy (kills the semantic-HTML identity).
• Theming contract — two tiers. Tier 1 = a hard-capped ~20 tokens that are a theme (--bg --fg --surface --accent --accent-content --radius --space --ease-hikari, etc.), every accent paired with a readable --accent-content. Tier 2 = internal component tokens derived from Tier 1 via OKLCH color-mix(); users never touch them. Depth/glow are mixed from --accent, so switching theme recolors shadows for free.
• Color engine — OKLCH + color-mix(), no legacy fallback. Modern browsers only.
• Theme application — data-theme on a container; themes nest. Dark mode auto via @media (prefers-color-scheme), overridable by any data-theme.
• Cascade — everything wrapped in @layer hikari. User overrides (unlayered) always win with no !important. Accepted consequence: Hikari yields to any pre-existing unlayered site CSS; positioned as "for pages you own."
• Authoring & build — plain modern CSS partials (native nesting, @layer, color-mix(), :has()); Lightning CSS is the sole dev-dependency (bundle + minify + downlevel). No preprocessor.
• Distribution — one CDN <link> + npm hikariui shipping hikari.min.css, hikari.css, themes/*.css, and optional hikari.js. Messaging drops "tree-shaking" and "zero deps/runtime"; keeps "no framework dependency."
• JS helper — hikari.js, optional, ~1–2kb, dependency-free: theme switch + persistence, <dialog> open (native command/commandfor invoker where supported, JS fallback otherwise), toast dismiss. Plus a mandatory inline no-FOUC snippet (can't be deferred). Every helper also documented as raw vanilla.
• Design language. Quiet near-monochrome surfaces + ma spacing; one rationed electric accent that ignites on interaction; one uniform easing curve --ease-hikari (fast-in, precise-settle) on every transition, gated by prefers-reduced-motion. Japanese references inform taste, not marketing.
• Agent-adoption layer — single canonical rules source, all surfaces derive from it (no drift). Canonical hikari-rules.md (doctrine + data-* vocabulary + ~20 tokens + do-nots) → llms.txt, AGENTS.md, and a skills.sh-installable Claude Code Skill. Rules quality is reputation-load-bearing; tune against real agent runs.
• Docs site — Astro (content-first, zero-JS default for a provable Lighthouse score, MDX). Hero = live theme-switch kitchen-sink that re-lights depth; second screen = token playground (JS lives in docs, not the framework). Build the site first as the design forcing-function.
• Doctrine (5 principles, shown not preached): (1) Semantic HTML is the API; (2) Taste is the default, the palette is yours; (3) Beautiful in, beautiful out; (4) Modern CSS, no apologies — platform progress, not breaking consumers' markup (visual/API stability is table stakes); (5) Your overrides always win.
• Rejected path: becoming a Tailwind plugin (DaisyUI-style). It would fight an entrenched clone, kill the semantic-HTML identity, and require Tailwind (contradicting "bloatfree"). Tailwind's distribution is recaptured via the agent-adoption layer instead.
• Deferred (not now, YAGNI): optional Tailwind preset exposing the ~20 tokens, built only if traction demands it.

Testing Decisions

• A good test asserts external, rendered behavior — how the page looks and computes with Hikari applied — never internal CSS structure (selector names, partial organization, token-derivation internals).
• One seam: Playwright against the built kitchen-sink page. Highest possible point; everything tests through the rendered page.
  • Visual regression — a screenshot per shipped theme, asserting the kitchen-sink renders correctly and re-lights (including shadows) on theme swap.
  • Computed-style / a11y assertions — the three non-negotiables, mechanically: every theme's accent/accent-content pair passes contrast; prefers-reduced-motion disables all transitions; an author override beats Hikari's @layer.
  • Theme validation — every shipped theme defines all Tier-1 tokens and passes the contrast gate (can run as a lightweight check over theme files, but the guarantee is verified through rendering).
• Prior art: none yet (greenfield). The Playwright kitchen-sink harness becomes the reference pattern for all future component specs.

Out of Scope

• Tier 3 components (documented as deliberately cut): combobox-with-filtering, carousel, date picker, multi-select, anything virtualized — they fail the minimalism test.
• The slop demo (same-prompt Tailwind-vs-Hikari before/after) — deferred; added only if launch gets "does it actually work?" pushback.
• Tree-shaking / modular per-component imports — dropped from v1 messaging; offered later only if asked.
• Legacy-browser fallbacks — modern browsers only.
• Becoming a Tailwind plugin and the deferred Tailwind preset.
• Retrofitting Hikari onto already-styled sites (WordPress heavy themes, existing global CSS) — Hikari deliberately yields there; it targets pages you control.

Further Notes

• Brand: Hikari UI · pkg hikariui · domains hikariui.com (+ .dev). Canonical GitHub repo pghqdev/HikariUI.
• Open fact to verify (not a decision): npm view hikariui is free → else fall back to unscoped hikari-ui.
• Suggested build order: (1) Astro site skeleton + empty kitchen-sink page; (2) Tier-1 tokens + --ease-hikari + light/dark themes, proving the recolor loop on plain elements; (3) dialog + tabs, then the rest of the hero set; (4) theme switcher + token playground; (5) agent-adoption layer. Prove the two unvalidated bets first — do the defaults look great cold, and can a ruled agent out-taste freestyle Tailwind.