jeen design system — v0.6.13
A living, AI-queryable design system that is also the portfolio. Design decisions exist as structured data — visible through a dashboard, queryable through an agent.
Registry snapshot at v0.6.13. All values sourced from system.json → stats.
Observed usage from static analysis of src/. Source: system.generated.json (2026-05-15). Independent of system.json registry declarations.
UI components only. Adoption status reflects direct import usage in product files, not DS showcase.
These CSS classes are applied directly in source files instead of using the corresponding system component. Does not include DS showcase (components.astro).
Raw link classes used in DS route navigation. Ironic: components.astro imports Link for demos but still uses raw classes in its own nav.
All issues tracked in system.json → discrepancies, updated by /review-ds.
.article-meta uses --color-gray-500 on dark article header — WCAG AA fail
homepage.css line ~1551: .article-meta has color:var(--color-gray-500) (#6A6A60). Article header background is --color-black (#0A0A0A). Contrast ratio ~1.6:1 — fails WCAG AA. Should use --fg-on-dark-label (~5:1) or --fg-on-dark-secondary (~9:1).
Logged 2026-05-04dashboard.astro used --color-warning and --color-success as inline text colors on light surface
Phase 3 dashboard rewrite introduced three inline contrast violations: (1) color:var(--color-warning) = #F3FE52 (yellow) as text on ds-table light surface (~1:1 contrast); (2) color:var(--color-success) = #3DFE87 (neon green) as text on ds-table light surface (~1.3:1); (3) color:var(--fg-tertiary) at 11px on light surface (2.6:1, fails AA). Fixed: replaced with --fg-primary (bold emphasis) and --fg-secondary (secondary text) respectively. --color-warning and --color-success are safe as backgrounds or on --bg-dark; never use as text on light surfaces.
Resolved in 5efb7e8 · 2026-05-14rgba() tints used in dash-stat state modifiers — intentional, no token equivalent
dashboard v1 stat cards use rgba() tints derived from --color-warning (yellow 6%), --color-error (red 6%), and --color-success (green 6%) for subtle state backgrounds (.dash-stat--warn, --critical, --ok). CLAUDE.md permits rgba tints for subtle overlays when documented. No token for semi-transparent status surfaces exists. Annotated with inline comments in design-system.css.
Logged 2026-05-13Diary page styles not formally in DS: code blocks, HR
The diary page uses inverted code blocks (--bg-dark bg, --fg-on-dark-primary text) and styled HRs (gray-300 border) not defined in the DS token set. Consider formalising these as article-specific token aliases.
Ghost + coming-soon Badge variants not in DS spec
Playground section uses ghost-style category labels and coming-soon badges not defined in the DS badge spec. Currently implemented as one-off CSS in homepage.css. Consider adding ghost and coming-soon as official Badge variants with tokens.
.article-meta uses --color-gray-500 on dark article header — WCAG AA fail
homepage.css line ~1551: .article-meta has color:var(--color-gray-500) (#6A6A60). Article header background is --color-black (#0A0A0A). Contrast ratio ~1.6:1 — fails WCAG AA. Should use --fg-on-dark-label (~5:1) or --fg-on-dark-secondary (~9:1).
Doodle illustration set incomplete
DS spec calls for hand-drawn SVG doodles as a decorative layer (1–3 per section, black line art). Both feather_copy.svg and feather_check.svg have been removed (replaced by Lucide icons). Full doodle set to be provided by Jeen.
Several decorative border-radius values have no exact token (2px, 3px, 8px)
Audit found border-radius: 2px (.hero-scroll-dot, .mobile-menu-btn span, article hr divider), 3px (scrollbar thumb, .footer-brand-logo), and 8px (.mobile-menu-btn, hidden .footer-email-row button) in homepage.css with no corresponding token. The token scale goes --radius-xs (4px), --radius-sm (6px), --radius-md (12px). These are all decorative micro-chrome elements. Decision: either add --radius-2xs: 2px and --radius-2sm: 3px / 8px tokens, or accept raw values for sub-4px decorative radii. Currently left as-is pending token scale decision.
102 tokens across 7 categories. Source of truth: src/styles/tokens.css. Values: system.json → tokens.categories.
Color
6 sub-groups — primitive, semantic, on-dark, interactive
Spacing
Scale (13) + layout (4) · base 8px
Typography
3 families, 12-step scale, leading, tracking
Shadow
6 hard-offset + 2 soft
Radius
7-step scale — none → full
Border
Pick by surface: border-primary/subtle on light, border-on-dark on --bg-dark, border-accent for highlights
Animation
3 easings + 3 durations
Primitive (18)
Raw values — use in DS documentation only, never in product code
--color-black--color-white--color-pure-white--color-yellow--color-yellow-dim--color-yellow-pale--color-gray-50--color-gray-100--color-gray-200--color-gray-300--color-gray-400--color-gray-500--color-gray-700--color-gray-900--color-success--color-warning--color-error--color-info Semantic (19)
Intent-named — use in all product code; describes purpose not value
--bg-primary--bg-dark--bg-accent--bg-accent-dim--bg-surface--bg-surface-raised--bg-inverse--fg-primary--fg-secondary--fg-tertiary--fg-inverse--fg-accent--fg-on-dark-primary--fg-on-dark-secondary--fg-on-dark-label--fg-on-dark-accent--color-focus--color-cta--color-cta-hover useSemanticFirst Always prefer semantic tokens (--fg-primary) over primitives (--color-black) in product code noHardcodedValues Never hardcode hex colors, font names, spacing, shadows, or border radii if a token exists noNewTokens Do not add CSS variables outside of tokens.css a11yLightSurface --fg-tertiary fails WCAG AA at small sizes on light bg — use --fg-secondary minimum a11yDarkSurface Only --fg-on-dark-* tokens on --bg-dark. Never gray-500/700/900 on dark. a11yYellowSurface Only --color-black on yellow — all other values fail contrast 9 components from system.json → components. Adoption status is code-observed (system.generated.json), not registry-declared.
Global page infrastructure — shell, header, footer. Required on every page. Not subject to variant expansion.
Reusable design system primitives — Badge, Button, Card, Link, IconButton. These carry variants and are the building blocks of product pages.
Internal tooling — TweaksPanel and future edit-mode overlays. Not for product use; may use window APIs.
Declared relationships from system.json → relationships.
These are registry-declared intent, not code-observed adoption counts.
For actual usage data, see section 02 Code Observability.
/ /design-system /design-system-foundations /design-system-components /design-system-dashboard /diary-slug / /design-system /design-system-foundations /design-system-components /design-system-dashboard /diary-slug hero playground about work Merged timeline of discrepancies, diary entries, and releases. Latest first.
v0.6.13 released
Add roadmap[] to system.json with 5 items (next/planned/later). Render as section 08 on dashboard. Phase 6 observability automation also ships in this version.
.footer-copy-btn contrast — resolved: class renamed, surface changed
Originally tracked as .footer-copy-btn with --color-gray-500 on dark surface. Audit 2026-05-14: class .footer-copy-btn n…
Hero.astro SVG squiggle used hardcoded #F3FE52 instead of --color-yellow token
The decorative squiggle SVG in Hero.astro used stroke='#F3FE52' as a presentation attribute — a hardcoded hex where --co…
dashboard.astro used --color-warning and --color-success as inline text colors on light surface
Phase 3 dashboard rewrite introduced three inline contrast violations: (1) color:var(--color-warning) = #F3FE52 (yellow)…
rgba() tints used in dash-stat state modifiers — intentional, no token equivalent
dashboard v1 stat cards use rgba() tints derived from --color-warning (yellow 6%), --color-error (red 6%), and --color-s…
Dogfooding My Design System: Building Something That Watches Itself
Workflow · 5 min read → /diary/dogfooding-my-design-system
Link variant='subtle' removed from system
variant='subtle' (.link-subtle) was deprecated in 0.5.1 and never used in any product page. Fully removed in 0.6.1: CSS …
2× hardcoded border-radius: 12px in homepage.css
Audit found .hero-scroll-mouse (line 343) and .footer-email-row responsive override (line 1457) using border-radius: 12p…
IconButton missing from component-inventory.md
IconButton was created and added to system.json in v0.5.7 but omitted from component-inventory.md. Full section added: p…
Header.jsx uses hardcoded hex, font-family strings, and raw box-shadow values
Refactored Header.jsx to remove all inline style objects. Added CSS classes nav, nav.nav--active, .nav-inner, .nav-logo-…
Several decorative border-radius values have no exact token (2px, 3px, 8px)
Audit found border-radius: 2px (.hero-scroll-dot, .mobile-menu-btn span, article hr divider), 3px (scrollbar thumb, .foo…
.article-meta uses --color-gray-500 on dark article header — WCAG AA fail
homepage.css line ~1551: .article-meta has color:var(--color-gray-500) (#6A6A60). Article header background is --color-b…
/design-system split into 4 routes instead of tab-based single page
The single design-system.astro monolith (1270 lines, JS tab switching) was refactored into /design-system (hub), /design…
Ad-hoc link styles unified into Link component + global pattern
6 ad-hoc link styles (nav-link, hero-social-link, footer-link, footer-contact-link, social-pill, article-back-link) were…
Upcoming system work. Source: system.json → roadmap.
Improve dashboard communication layer
Refactor how system data is surfaced on the dashboard — clearer data provenance, better separation between registry-declared intent and code-observed adoption, and tighter section descriptions.
→ Dashboard becomes self-explanatory to a first-time visitor without needing external context.
Add regression tracking
Extend the observability script to detect regressions: raw CSS mimics appearing in files that previously used direct imports, or variant usage dropping out of variantsUsedDirectly.
→ Migrations cannot silently regress. The script flags regressions on every run.
Integrate analyze-system into /review-ds
Make /review-ds automatically run npm run analyze-system before auditing, so system.generated.json is always fresh and adoption data in the audit report reflects the current diff.
→ Single command produces both fresh observability data and a complete audit report. No manual regeneration step.
Ask Pocky v0
First version of the AI agent interface — allow visitors to query the design system through Pocky. Backed by system.json and system.generated.json as structured context.
→ Visitors can ask questions like 'which components are partially adopted?' and get accurate, data-driven answers directly from the system.
Component sandbox
An interactive playground where visitors can configure component props and see live rendered output. Each system component (Badge, Button, Card, Link, IconButton) would have a sandbox pane on the components page.
→ The components page becomes a hands-on reference, not just documentation.