@ponchia/ui 0.3.2 → 0.3.3

package/docs/theming.md

@@ -0,0 +1,160 @@
+# Theming & branding contract
+
+`@ponchia/ui` is one framework meant to dress several different projects.
+This is the **stable, supported surface** for re-branding without forking.
+Anything not listed here is internal and may change between minor versions.
+
+## The one knob: `--accent`
+
+The whole accent family derives from `--accent` via `color-mix()`:
+
+| Token                 | Derivation (light / dark)                    | Role |
+| --------------------- | -------------------------------------------- | ---- |
+| `--accent-strong`     | `--accent` mixed 83% with black / 84% white  | darker/lighter accent for hover, emphasis |
+| `--accent-text`       | `var(--accent-strong)` (alias)               | **accent used as foreground text** — the on-surface, AA-safe one |
+| `--accent-soft`       | `--accent` at 10% / 14% over transparent     | tinted fills |
+| `--bg-accent`         | `--accent` at 6% / 8%                         | faint accent backgrounds |
+| `--field-dot-accent`  | `--accent` at 78% / 82%                       | form dot indicators |
+| `--focus-ring`        | `var(--accent)` (solid)                       | **every focus outline** — override to tune the ring alone |
+
+So a full re-brand is one declaration — globally or on any subtree:
+
+```css
+:root      { --accent: #2f6df6; }   /* brand the whole app blue   */
+.promo     { --accent: #16a34a; }   /* …or just this section green */
+:root[data-theme='dark'] { --accent: #6ea8ff; } /* per-theme tuning */
+```
+
+Everything — buttons, focus rings, dot motifs, accent borders, soft
+fills — follows automatically, in both light and dark.
+
+> **Two contrast obligations when you change `--accent`:**
+>
+> 1. **Buttons** — pick an `--accent` with ≥ 4.5:1 against `--button-text`
+>    (white in light, black in dark) for accessible primary buttons.
+> 2. **Accent-as-text** — anywhere the accent is foreground text (links,
+>    active nav/tabs, eyebrows, chips) the framework uses `--accent-text`,
+>    **not** raw `--accent`, so it stays AA on surfaces. `--accent-text`
+>    defaults to `--accent-strong` (a darkened/​lightened accent). If you
+>    re-brand to a pale hue, raw `--accent` would fail as text — override
+>    `--accent-text` to a sufficiently dark/light value rather than
+>    relying on the 83%/84% mix.
+>
+> The defaults are tuned for both; verify if you deviate hard. The focus
+> ring is solid `--accent` (≥ 3:1 non-text) — re-brand to a near-`--bg`
+> hue and you must also raise `--focus-ring` (it's an independent knob).
+
+## Other supported knobs
+
+- **Spacing** — override the `--space-2xs … --space-2xl` scale, or use a
+  preset: `data-density="compact"` / `data-density="comfortable"` on any
+  element (defaults to the middle scale).
+- **Radius** — `--radius-sm … --radius-xl`, `--radius-pill`. The Nothing
+  default is near-sharp; raise these for a softer brand.
+- **Type** — `--display` (dot-matrix face), `--mono`, `--sans`. Override
+  to drop Doto or swap the body face; the token layer keeps working even
+  if you self-host fonts (see the `fonts.css` note in the README).
+- **Surfaces / lines / text** — the `--bg*`, `--panel*`, `--line*`,
+  `--text*` tokens are overridable for a bespoke palette, but you then
+  own their contrast. Prefer just `--accent` unless you need a full
+  re-skin.
+- **Native controls** — checkbox/radio/range tick marks use the CSS
+  `accent-color: var(--accent)` (browser-rendered). The check glyph
+  colour is the UA's choice and not in our control, so a very light
+  `--accent` (e.g. a pale yellow) can make native checkmarks low-
+  contrast. If you re-brand to a light hue, verify native controls or
+  set `accent-color` yourself on them — this is the one accent surface
+  the framework can't tune for you.
+
+## Token tiers (0.3.1)
+
+Three additive, non-breaking tiers sit on top of the primitives. The
+short legacy names (`--panel`, `--line`, `--accent`, …) keep working
+forever as aliases — the tiers are about giving consumers stabler,
+coarser-grained handles.
+
+- **Semantic tier — `--bronto-color-*`.** Role-named aliases:
+  `--bronto-color-surface`, `-surface-raised`, `-border`,
+  `-border-strong`, `-text`, `-text-muted`, `-action`, `-on-action`,
+  `-focus`, `-success`, `-warning`, `-danger`, `-bg`. Target these in
+  new consumer code: re-skinning a _role_ is now one override instead of
+  chasing component internals. They resolve through the per-theme
+  primitives, so light/dark still Just Works.
+- **Accent ramp — `--accent-1 … --accent-6`.** A stepped family
+  (subtle → bold) derived from the single `--accent` knob via
+  `color-mix` against the theme background. Re-brands and theme-adapts
+  automatically. This is the palette for charts / data-viz / multi-state
+  surfaces (the use case the JS token export advertises).
+- **Neutral ramp — `--surface-1 … --surface-6`** (low → high contrast
+  against `--bg`) for layered surfaces without hand-picking greys.
+- **Stacking scale — `--z-base / -raised / -sticky / -overlay /
+  -popover / -toast`.** Every framework `z-index` now resolves through
+  these; override one to slot your app's own layers around the
+  framework's without specificity/`z-index` wars.
+
+All four tiers are in the DTCG export and the JS token model.
+
+## Accessibility markup contracts
+
+A few components are styled but need the consumer to author the right
+semantics — the CSS can't add ARIA for you:
+
+- **`.ui-switch`** — put `role="switch"` on the `<input type="checkbox">`.
+  It then announces "switch, on/off" and the native `checked` drives
+  `aria-checked` (no JS). Forced-colors state cues ship in `forms.css`.
+- **`.ui-tab` / tabs** — operability requires `initTabs()`; don't
+  server-render panels `hidden` unless it's guaranteed to run (see the
+  `initTabs` doc comment).
+- **`.ui-combobox`** — use `initCombobox()`; it owns the APG ARIA.
+- **`.ui-tooltip`** — fine for short labels; for edge-critical or rich
+  content use `.ui-popover` + `initPopover()` (collision-aware).
+
+> **Verify a rebrand:** open
+> [`demo/theme-playground.html`](../demo/theme-playground.html) — paste
+> your `--accent`, see the derived family and the computed WCAG ratios
+> for `--accent-text` / `--accent` against the surface, and copy the CSS
+> + DTCG override. This is the instrument for the "verify your hue"
+> obligation below.
+
+## Contrast
+
+- `data-contrast="high"` on any element, **and** the OS
+  `prefers-contrast: more` signal, collapse the soft greys toward the
+  strong end (hairlines → `--line-strong`, dim text → `--text-soft`,
+  solid focus ring). Theme-agnostic — they reference the per-theme
+  `*-strong` tokens, so they work under light and dark.
+- Windows High Contrast / `forced-colors: active` is handled in
+  `base.css`: state that was signalled only by a fill (progress, status
+  dots, switch, segmented) is re-asserted with system colors.
+
+## Design-token interop (DTCG)
+
+`@ponchia/ui/tokens.dtcg.json` is the token model in the W3C Design
+Tokens Community Group format, for Style Dictionary / Figma / other
+tooling. Generated from `tokens/index.js` and drift-checked by
+`npm run check`. Resolvable primitives (the scale, `--accent`, literal
+palette) carry real `$value`s; the CSS-runtime-derived family
+(`accent-soft`, `focus-ring`, aliases) is spec-shaped with
+`$value: null` + the CSS in `$extensions["com.ponchia.css"]` rather than
+fabricating a number — the resolvable knob is `color.<theme>.accent`.
+
+## Reading tokens from JS
+
+`@ponchia/ui/tokens` exposes the model as data. The ergonomic view only
+strips the `--` prefix — **keys stay kebab-case**, so they must be
+bracket-accessed: `themeColor('dark')['accent-soft']`, **not**
+`.accentSoft`. (`themeColor('dark').accent` works only because `accent`
+is a single word.) `--accent` and the non-derived colors resolve to
+literal hex; the derived members (`accent-strong`, `accent-soft`,
+`focus-ring`, …) are `color-mix(…)` / alias strings — resolve them in the
+DOM via `getComputedStyle` if you need the final value, or just read/​set
+`--accent` itself. The `.d.ts` now types these keys as literal unions
+(`ColorKey`/`ScaleKey`), so a mistyped key is a compile error and
+autocomplete lists the real names.
+
+## Stability
+
+The token **names** and the `--accent` derivation are the contract and
+are covered by `npm run check` (the `tokens.css ⇄ tokens/index.js ⇄
+index.json` drift check). Token **values** may be tuned within a theme;
+treat a value change as visual, a name/derivation change as breaking.

package/llms.txt

@@ -0,0 +1,85 @@
+# @ponchia/ui
+
+> CSS-first, framework-agnostic UI framework. Zero runtime dependencies.
+> One `@layer bronto` cascade, a typed class vocabulary, design tokens as
+> data, and optional SSR-safe vanilla behaviors. Nothing-inspired:
+> monochrome surfaces, a single rationed accent, dot-matrix display type.
+>
+> This file orients an LLM/agent. The authoritative, always-correct API
+> is the TypeScript declarations shipped in this package (paths below):
+> they are generated from the runtime sources and CI-drift-checked, so
+> they never lie. Read them before guessing class or token names.
+
+## Use the framework
+
+CSS (pick one; do not import both):
+
+```css
+@import '@ponchia/ui';        /* dist/bronto.css — flattened, minified, one file (recommended) */
+@import '@ponchia/ui/css';    /* css/core.css — @import fan-out, needs a bundler */
+```
+
+Everything lands in `@layer bronto`. Consumer styles in no layer (or a
+later layer) always win over framework styles regardless of selector
+specificity — this is the intended override mechanism; do not fight it
+with `!important`.
+
+Typed class vocabulary (returns plain strings — works in any framework):
+
+```js
+import { cls, ui, cx } from '@ponchia/ui/classes';
+// ui.button({ variant: 'ghost' }) -> "ui-button ui-button--ghost"
+// cx(ui.dot({ tone: 'success' }), 'my-extra') -> joined, falsy-skipped
+// cls is the frozen flat registry of every class the framework defines
+```
+
+Tokens as data (theming + reading the palette):
+
+```js
+import { cssVars, tokens, themeColor } from '@ponchia/ui/tokens';
+```
+
+Optional vanilla behaviors (theme toggle, etc. — SSR-safe, tree-shakeable):
+
+```js
+import { applyStoredTheme } from '@ponchia/ui/behaviors';
+```
+
+## Authoritative offline references (shipped in this package)
+
+Read these from `node_modules/@ponchia/ui/` — no network needed:
+
+- `classes/index.d.ts` — literal-typed `cls` map (exact class strings),
+  every `ui.*()` recipe signature, every `*Opts` interface. The complete
+  class surface; an agent should read this to know valid class names.
+- `docs/reference.md` — the full class catalog as prose tables (every
+  class grouped by component, with registry key + kind). Generated from
+  the same source as the types and CI-drift-checked.
+- `docs/theming.md` — the token contract: which tokens to override, the
+  light/dark model, and the rationed-accent rule.
+- `tokens/index.d.ts` — every design-token name as a literal union.
+- `tokens/index.json` — tokens as plain data (global / light / dark).
+- `tokens/tokens.dtcg.json` — same tokens in W3C DTCG format.
+- `tokens/resolved.json` — every colour token resolved to a static
+  `#rrggbb` / `rgba(...)` per theme (var() + color-mix() evaluated).
+  Use this for non-CSS render targets: MapLibre/canvas/WebGL/SVG.
+- `behaviors/index.d.ts` — typed signatures for the optional behaviors.
+- `classes/vscode.css-custom-data.json` — editor autocomplete for tokens.
+
+## Human-browsable references (not shipped in the npm tarball, by design)
+
+- Live kitchen-sink demo (every component, light/dark, RTL): https://ponchia.github.io/bronto-ui/
+- Architecture & the CSS-first decision: https://github.com/Ponchia/bronto-ui/blob/main/docs/architecture.md
+- Framework integration guides (Astro / SvelteKit / React-Solid / vanilla):
+  https://github.com/Ponchia/bronto-ui/tree/main/docs/getting-started
+
+## Rules an agent should respect
+
+- Never invent `ui-*` class names. Every valid class is a member of
+  `cls` in `classes/index.d.ts`; if it is not there, it does not exist.
+- Prefer the `ui.*()` recipes over hand-concatenating modifier strings.
+- Override framework styles by writing your own rules outside
+  `@layer bronto` — not with higher specificity or `!important`.
+- The accent color is deliberately rationed (monochrome + one accent).
+  Do not introduce new hues; theme via the documented tokens only.
+- Pre-1.0 SemVer: breaking changes ship in the *minor*. Pin `~0.x`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponchia/ui",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module",
   "description": "Shared Bronto UI framework — Nothing-inspired monochrome CSS theme, dot-matrix motifs, admin shell.",
   "license": "MIT",
@@ -24,7 +24,10 @@
     "tokens",
     "classes",
     "behaviors",
-    "shiki"
+    "shiki",
+    "llms.txt",
+    "docs/reference.md",
+    "docs/theming.md"
   ],
   "style": "./dist/bronto.css",
   "scripts": {
@@ -34,6 +37,7 @@
     "check:format": "prettier --check .",
     "tokens:build": "node scripts/gen-tokens-json.mjs",
     "dtcg:build": "node scripts/gen-dtcg.mjs",
+    "resolved:build": "node scripts/gen-resolved.mjs",
     "dts:build": "node scripts/gen-dts.mjs",
     "reference:build": "node scripts/gen-reference.mjs",
     "vscode:build": "node scripts/gen-vscode-data.mjs",
@@ -44,15 +48,16 @@
     "check:dts": "node scripts/check-dts.mjs",
     "check:types": "tsc -p tsconfig.json",
     "check:dtcg": "node scripts/check-dtcg.mjs",
+    "check:resolved": "node scripts/check-resolved.mjs",
     "check:shiki": "node scripts/check-shiki.mjs",
     "check:dist": "node scripts/check-dist.mjs",
     "check:pack": "node scripts/check-pack.mjs",
     "check:release": "node scripts/check-release.mjs",
     "check:reference": "node scripts/check-reference.mjs",
     "check:vscode": "node scripts/check-vscode-data.mjs",
-    "check": "npm run lint && npm run check:format && npm run check:exports && npm run check:tokens && npm run check:classes && npm run check:dts && npm run check:types && npm run check:dtcg && npm run check:shiki && npm run check:dist && npm run check:pack && npm run check:release && npm run check:reference && npm run check:vscode",
+    "check": "npm run lint && npm run check:format && npm run check:exports && npm run check:tokens && npm run check:classes && npm run check:dts && npm run check:types && npm run check:dtcg && npm run check:resolved && npm run check:shiki && npm run check:dist && npm run check:pack && npm run check:release && npm run check:reference && npm run check:vscode",
     "test": "node --test \"test/*.test.mjs\"",
-    "prepack": "npm run tokens:build && npm run dtcg:build && npm run dts:build && npm run reference:build && npm run vscode:build && npm run dist:build",
+    "prepack": "npm run tokens:build && npm run dtcg:build && npm run resolved:build && npm run dts:build && npm run reference:build && npm run vscode:build && npm run dist:build",
     "prepublishOnly": "npm run check && npm test"
   },
   "devDependencies": {
@@ -110,7 +115,11 @@
     "./vscode.css-custom-data.json": "./classes/vscode.css-custom-data.json",
     "./tokens.json": "./tokens/index.json",
     "./tokens.dtcg.json": "./tokens/tokens.dtcg.json",
+    "./tokens/resolved.json": "./tokens/resolved.json",
     "./shiki/nothing.json": "./shiki/nothing.json",
+    "./llms.txt": "./llms.txt",
+    "./docs/reference.md": "./docs/reference.md",
+    "./docs/theming.md": "./docs/theming.md",
     "./classes": {
       "types": "./classes/index.d.ts",
       "default": "./classes/index.js"

package/tokens/resolved.json

@@ -0,0 +1,125 @@
+{
+  "$comment": "@ponchia/ui colour tokens resolved to static values per theme (var() + sRGB color-mix() evaluated at build). For non-CSS render targets: MapLibre/canvas/WebGL/SVG. Generated from tokens/index.js — do not edit by hand; run `npm run resolved:build`. Drift-checked in CI.",
+  "light": {
+    "--accent-1": "#f2e2e1",
+    "--accent-2": "#efd1d1",
+    "--accent-3": "#ebaeaf",
+    "--accent-4": "#e37175",
+    "--accent-5": "#d71921",
+    "--accent-6": "#b2151b",
+    "--surface-1": "#f4f4f2",
+    "--surface-2": "#fbfbfa",
+    "--surface-3": "#ffffff",
+    "--surface-4": "#ececea",
+    "--surface-5": "#d8d8d4",
+    "--surface-6": "#a8a8a2",
+    "--bronto-color-bg": "#f4f4f2",
+    "--bronto-color-surface": "#ffffff",
+    "--bronto-color-surface-raised": "#ffffff",
+    "--bronto-color-border": "#d8d8d4",
+    "--bronto-color-border-strong": "#a8a8a2",
+    "--bronto-color-text": "#0a0a0a",
+    "--bronto-color-text-muted": "#686863",
+    "--bronto-color-action": "#d71921",
+    "--bronto-color-on-action": "#ffffff",
+    "--bronto-color-focus": "#d71921",
+    "--bronto-color-success": "#2f7d4f",
+    "--bronto-color-warning": "#806414",
+    "--bronto-color-danger": "#c01622",
+    "--surface": "#ffffff",
+    "--surface-raised": "#ffffff",
+    "--surface-muted": "#ececea",
+    "--border": "#d8d8d4",
+    "--border-strong": "#a8a8a2",
+    "--bg": "#f4f4f2",
+    "--bg-elevated": "#fbfbfa",
+    "--bg-accent": "rgba(215, 25, 33, 0.06)",
+    "--panel": "#ffffff",
+    "--panel-strong": "#ffffff",
+    "--panel-soft": "#ececea",
+    "--line": "#d8d8d4",
+    "--line-strong": "#a8a8a2",
+    "--text": "#0a0a0a",
+    "--text-soft": "#353533",
+    "--text-dim": "#686863",
+    "--accent": "#d71921",
+    "--accent-strong": "#b2151b",
+    "--accent-text": "#b2151b",
+    "--accent-soft": "rgba(215, 25, 33, 0.1)",
+    "--success": "#2f7d4f",
+    "--success-soft": "rgba(47, 125, 79, 0.12)",
+    "--warning": "#806414",
+    "--warning-soft": "rgba(128, 100, 20, 0.13)",
+    "--orange": "#a85f32",
+    "--orange-soft": "rgba(168, 95, 50, 0.13)",
+    "--danger": "#c01622",
+    "--danger-soft": "rgba(192, 22, 34, 0.1)",
+    "--code-bg": "rgba(10, 10, 10, 0.05)",
+    "--button-text": "#ffffff",
+    "--field-dot": "rgba(10, 10, 10, 0.16)",
+    "--field-dot-hot": "rgba(10, 10, 10, 0.4)",
+    "--field-dot-accent": "rgba(215, 25, 33, 0.78)",
+    "--focus-ring": "#d71921"
+  },
+  "dark": {
+    "--accent-1": "#140505",
+    "--accent-2": "#29090a",
+    "--accent-3": "#521315",
+    "--accent-4": "#992327",
+    "--accent-5": "#ff3b41",
+    "--accent-6": "#ff5a5f",
+    "--surface-1": "#000000",
+    "--surface-2": "#0a0a0a",
+    "--surface-3": "#0c0c0c",
+    "--surface-4": "#1a1a1a",
+    "--surface-5": "#2a2a2a",
+    "--surface-6": "#444444",
+    "--bronto-color-bg": "#000000",
+    "--bronto-color-surface": "#0c0c0c",
+    "--bronto-color-surface-raised": "#141414",
+    "--bronto-color-border": "#2a2a2a",
+    "--bronto-color-border-strong": "#444444",
+    "--bronto-color-text": "#f2f2f2",
+    "--bronto-color-text-muted": "#858585",
+    "--bronto-color-action": "#ff3b41",
+    "--bronto-color-on-action": "#000000",
+    "--bronto-color-focus": "#ff3b41",
+    "--bronto-color-success": "#4ec27e",
+    "--bronto-color-warning": "#d8bd72",
+    "--bronto-color-danger": "#ff4d54",
+    "--surface": "#0c0c0c",
+    "--surface-raised": "#141414",
+    "--surface-muted": "#1a1a1a",
+    "--border": "#2a2a2a",
+    "--border-strong": "#444444",
+    "--bg": "#000000",
+    "--bg-elevated": "#0a0a0a",
+    "--bg-accent": "rgba(255, 59, 65, 0.08)",
+    "--panel": "#0c0c0c",
+    "--panel-strong": "#141414",
+    "--panel-soft": "#1a1a1a",
+    "--line": "#2a2a2a",
+    "--line-strong": "#444444",
+    "--text": "#f2f2f2",
+    "--text-soft": "#c4c4c4",
+    "--text-dim": "#858585",
+    "--accent": "#ff3b41",
+    "--accent-strong": "#ff5a5f",
+    "--accent-text": "#ff5a5f",
+    "--accent-soft": "rgba(255, 59, 65, 0.14)",
+    "--success": "#4ec27e",
+    "--success-soft": "rgba(78, 194, 126, 0.14)",
+    "--warning": "#d8bd72",
+    "--warning-soft": "rgba(216, 189, 114, 0.14)",
+    "--orange": "#d08c5b",
+    "--orange-soft": "rgba(208, 140, 91, 0.15)",
+    "--danger": "#ff4d54",
+    "--danger-soft": "rgba(255, 77, 84, 0.15)",
+    "--code-bg": "rgba(255, 255, 255, 0.05)",
+    "--button-text": "#000000",
+    "--field-dot": "rgba(242, 242, 242, 0.14)",
+    "--field-dot-hot": "rgba(242, 242, 242, 0.36)",
+    "--field-dot-accent": "rgba(255, 59, 65, 0.82)",
+    "--focus-ring": "#ff3b41"
+  }
+}