"Page name — Site name", em dash with spaces. ≤60 chars. Page name FIRST: a tab truncates from the right, and at eight visible characters the page name is the only distinguishing part. A sub-domain home page drops the repetition — "tanghoong design system", not "Home — tanghoong design system". description ≤160 chars, one sentence, written for a person. og:title same as <title>. og:image 1200x630, required or links preview blank. h1 one per page; may be shorter than the title, which carries the site name where the h1 does not. Keep the site name byte-identical across a property. ## Prose `.prose` on the wrapper, then unclassed HTML inside — Markdown output drops straight in. Spacing is the owl selector `.prose > * + *`. Caps at 68ch. .lede 56ch · .quote / blockquote 60ch + .quote-note .eyebrow (uppercase label above a heading) · .article-head + .article-meta .steps (CSS counter, mono accent numbers) · .codeblock · .code-inline · .kbd .measure 68ch · .measure-tight 56ch · .measure-wide 80ch .measure-headline 20ch · --tight 16ch (big type needs a much tighter cap) Links inside .prose underline always; hover-only is undiscoverable mid-paragraph. content.css ends with a print block that drops all chrome. ## SVG and data graphics Icons: 24px viewBox, rendered 16-20px, `fill="none" stroke="currentColor"`, `stroke-linecap/linejoin="round"`. Stroke width tracks RENDERED size, not the viewBox: 12-14px→2.4, 16px→2, 18-20px→1.8, 24px+→1.5. Never hard-code a hex in an icon — currentColor is what makes it work on a filled button and in both themes. Decorative → `aria-hidden="true"` with the label on the control. Meaningful → `role="img"` + an aria-label stating the actual figures. ### The card system Self-contained SVG cards (the github.com/tanghoong profile README pattern — generated by scripts/generate-cards.mjs, committed as static files, no third-party badge service in the render path): 880px wide always, so a column of cards aligns. Height varies: 168 stat row, 208 stats/two-panel, 268 columns, 276 share bar, 336 radar, 356 blocks, 428 year clock. Order the column most-signal-first; tallest and most decorative last, where its height costs the reader nothing. frame: <rect x="0.5" y="0.5" rx="20" fill=--bg-elevated stroke #000 @0.1 light / #fff @0.13 dark> (rx 20 = --r-lg) the 0.5 offset keeps a 1px stroke crisp — a whole-pixel edge renders as 2px padding 24 · title baseline y=36 · subtitle y=54 · plot area starts y=84 (y=40 for the title when there is no subtitle; left margin 54 when the plot needs axis values; two-panel cards split at 24..416 and 464..856) ### Type in SVG (raw px — SVG has no rem, so it ignores the user font setting) 30/700/-0.9 headline figure in a stat column 20/700/-0.6 secondary figure 14/600/-0.2 card title 12/600/-0.07 panel heading, series name 11/600/-0.07 label inside a filled block 10/600/+0.7 UPPERCASE stat label — positive tracking, it is set in caps 10/400/-0.06 card subtitle, date range, footnote 9/600/-0.05 axis caption · 9/400/-0.06 axis value 8.5/600/-0.05 month label on the year clock — the floor Same stack as --font-sans. Every figure gets font-variant-numeric:tabular-nums. Nothing essential may live only in SVG text; it must also be in the aria-label. ### The ramp is a function, not a palette Interpolate --c-from → --c-to and sample at N, IN OKLAB not sRGB. sRGB looks like the obvious choice and produces perceptually uneven steps that bunch at one end — the first version of this ramp did that and three of its six steps were indistinguishable. Use scripts/ramp.mjs. Light #03744e → #7ee6c3; dark #4dff9b → #107f40. Index 0 is the largest series and IS the accent. The overview card samples 6, frameworks 10, languages 16 — all from the same two endpoints. --c-1..--c-6 are the six-sample case, for CSS which cannot interpolate. Six is the ceiling *for a legend*; past that, label each block in place or use a table. As the ramp lightens, label ink must flip from white to dark — roughly at the fourth step. That is the thing careless automation gets wrong. ### Charting idioms stat row 3 columns centred at 880/6, 880/2, 880*5/6; dividers at the thirds; figure + UPPERCASE label + a line giving it a denominator share bar one rounded track (rx = height/2, 8-10px tall), segments as plain paths over it — no clipPath needed, the track corners show blocks width proportional, height constant, rx=10, 4px gutter, labels inset 9px IN PLACE — this is how a card carries 10+ series columns gridlines behind the data in --chart-grid, axis values in the left margin, columns scaleY from the baseline radar 6 axes, 3 rings, accent polygon at fill-opacity 0.16 (not the 12% --accent-wash: this sits over gridlines and needs more body) year clock polar, inner r52 outer r124 — the hole matters, spokes converging on a point smear. Length AND colour carry the count, so it survives greyscale. For the shape of a year, not for reading a value off. comparison one pill per period; solid fill = now, dashed accent @0.45 with stroke-dasharray="3 3" = the reference being measured against ### Motion Five animations, all cubic-bezier(.22,1,.36,1) = --ease: .fade 260ms opacity 0 + translateY(6px) type, labels, gridlines (most used) .rise 420ms opacity 0 + translateY(12px) headline figures, whole blocks .grow 420ms scaleX(0) horizontal bars, share segments .bar 420ms scaleY(0) vertical columns from the baseline .draw 900ms stroke-dashoffset a trend line drawing on; ≤1 per card 260ms is --dur, 420ms is --dur-slow. Stagger 0.04-0.06s within a group, ~0.12s between groups; past ~0.6s total the reader is waiting, not watching. ### Two SVG-specific traps 1. An SVG carries its own <style>, so base.css's global reduced-motion rule cannot reach inside it. Repeat the guard as `@media (prefers-reduced-motion: no-preference) { … }` in every animated SVG. 2. An <img src="*.svg"> cannot see the page custom properties. Inline SVG uses var(--token) and currentColor; a file-loaded SVG needs a light/dark pair switched with <picture><source media="(prefers-color-scheme: dark)">. The <img alt> must carry the real figures, not "stats card". Also: transform-origin must be set explicitly in user units on anything that scales or rotates — an SVG element's default origin is the viewport corner, so without it every bar grows from the top-left of the whole card. ## Utilities .t2 .t3 .t-accent .t-danger · .sm .xs .lead · .mono .nums · .w-med .w-semi .center .end .mx-auto · .measure* · .vh (visually hidden, still announced) .hidden .flex-1 .no-wrap .truncate .clamp-2 .clamp-3 · .scroll-x .mt-2 .mt-3 .mt-4 .mt-6 .mt-8 .mt-12 .mt-16 (top margin only — bottom margins fight the owl selector) Every [id] gets scroll-margin-block-start so anchors clear the sticky header. ## Writing markup - Build from the vocabulary above before writing any new CSS. A genuinely new component goes in the right layer file with a comment saying what it is for and when NOT to use it. - Prefer logical properties: inline-size/block-size, inset-*, margin-inline, border-inline-start. The system ships in English and Chinese. - SVG icons 16–20px, `fill="none" stroke="currentColor" stroke-width="1.8–2"`, always `aria-hidden="true"`. An icon-only control needs `aria-label`. - One `<h1>` per page. Never skip a heading level. To render text at heading size without being a heading, style a `<p>` — do not add a second `<h1>`. ## Avoid - A second primary button in the same view. - A shadow in dark theme (they are `none`; use --bg-elevated for depth). - A tooltip carrying information available nowhere else. - A fifth breakpoint — try clamp(), minmax() or auto-fill first. - `vh` for full-height overlays; use `dvh` or mobile browser chrome clips them. - Any animation that ignores `prefers-reduced-motion: reduce`. ## Checking a page you generated node scripts/conform.mjs <file.html> --fail structural conformance node scripts/contrast.mjs --fail only if you touched tokens.css conform.mjs enforces the rules in this file and reports error/warn/info. A deliberate exception is declared in the page, not by weakening the rule:  Both scripts are dependency-free Node. Neither can see computed styles or runtime behaviour: they are a first pass, not a substitute for opening the page in both themes and tabbing through it. ## Ship checklist No literal hex/px/radius/duration outside tokens.css · both themes checked in both toggle directions · tabbed the whole page, focus ring visible everywhere · every field labelled, every error wired with aria-invalid + aria-describedby · every icon-only control has aria-label · one .btn--filled per view · no horizontal scroll at 320px · heading levels unbroken · checked with reduced motion forced on

# tanghoong design system > The shared visual language for tanghoong.com and every sub-domain. This file > is the complete specification. An agent that reads it does not need to crawl > the HTML pages — those exist for humans to look at. > > Version: 1.3.0 · Updated: 2026-09-06 > Source of truth: the files in /assets/css/ at https://design.tanghoong.com > Starter template for a new sub-domain: /template/index.html > Human documentation: /pages/*.html · Machine documentation: this file > > If you are building a page for any *.tanghoong.com property, read this file > in full first. Do not infer the system from a rendered page — the values here > are the ones that ship. ## Read this first - STARTING A NEW SUB-DOMAIN? Copy /template/index.html. It has the header, footer, nav sheet, theme toggle and meta block already wired correctly — the details that go wrong when rebuilt by hand are the invisible ones. - Copy `/assets/css/` into the project. Link in this order: tokens, base, layout, components, forms, overlays, content, utilities. Never ship docs.css. - The stylesheets are the artefact. There is no build step, no framework, no webfont, no CSS-in-JS. Plain HTML plus a class. - Full detail per topic: /pages/brand.html, /pages/foundations.html, /pages/layout.html, /pages/components.html, /pages/forms.html, /pages/overlays.html, /pages/loading.html, /pages/content.html, /pages/svg.html, /pages/patterns.html, /pages/prompt.html ## Non-negotiables 1. Never write a literal colour, font size, radius, shadow or duration in a component. Every value comes from a custom property in tokens.css. If the value you need does not exist, add it to tokens.css — do not inline it. 2. Never remove a focus outline without replacing it. Focus is `:focus-visible`, 2px `var(--focus)`, 2px offset. 3. Every interactive control clears a 44px touch target. 4. Every form field has a real ``. A placeholder is not a label. 5. Colour never carries meaning alone. Pair every status colour with a word. 6. Native element first: `