On this page
One shared component kit, one set of design tokens: a screen asks for a role and the active theme decides what it looks like, so the same screen is re-skinnable per deployment, organization and brand without a rewrite.
Core color tokens#
Default skin, light mode. Every role is a CSS custom property; dark mode and every skin redefine the same names, so a screen never hardcodes a hex value.
| Role | Token | Value |
|---|---|---|
| App background | - |
#f3f5fc |
| Card surface | - |
#ffffff |
| Primary text | - |
#192039 |
| Muted text | - |
#62687d |
| Accent | - |
#4d59d2 |
| Success | - |
#1fb57a |
| Warning | - |
#f4b740 |
| Danger | - |
#e24c4b |
| Info | - |
#2f7cff |
The kit#
@yng/ui is the component kit; every visible string is a prop, so nothing bypasses translation. DataTable is the default for rows (sorting, search, paging, export) and opens at 20 rows per page.
| Group | Primitives |
|---|---|
| Action | Button (with asChild to render as a link) |
| Form | Field, Input, Textarea, Select, Checkbox, Switch, RadioGroup, Radio, FieldGroup, FileInput |
| Overlay | Dialog (including the right-hand drawer posture), useConfirm / Confirm, Tooltip |
| Navigation | Tabs, TabList, Tab, TabPanel |
| Feedback | Toast, Alert, Skeleton, ErrorState |
| Data | DataTable, plus Table / Th / Td / Pagination for tables DataTable cannot absorb |
Typography roles#
Use nums-tabular on any number compared down a column; never add manual word-spacing per control.
Spacing and radius#
Spacing is named for the relationship it expresses, not a pixel count.
| Token | Size | Used between |
|---|---|---|
tight |
4px | Label and control |
snug |
8px | Items inside a control row |
field |
12px | Form fields, cell padding |
card |
16px | Card and dialog body |
gutter |
20px | Cards |
section |
24px | Page sections |
page |
32px | Page top and bottom |
| Radius role | Size | Used for |
|---|---|---|
rounded- |
6px | Badges, tags |
rounded- |
8px | Inner rows, small tiles |
rounded- |
10px | Inputs, buttons, switches |
rounded- |
14px | Cards, panels, table frames |
rounded- |
16px | Dialogs, popovers |
rounded- |
full | Switches, avatars, pills |
Elevation, stacking, motion#
A skin is mostly colour. It may adjust three radii (control, card, panel) and the two card shadows as one optional group, never stacking or motion; a brand override changes none of them.
Accessibility guarantees#
Built into the primitives, so a screen gets them by using the kit.
| Primitive | Guarantee |
|---|---|
| Dialog | Focus trapped and restored, Escape closes; a destructive confirm starts on Cancel |
| Tabs | Roving tab index; arrow keys move, Home/End jump; selection can mirror into the query string |
| Toast | Polite live region (assertive for errors); at most three shown at once |
| Tooltip | Opens on hover and focus, closes on Escape; never the only copy of a fact |
| Skeleton | One loading status region per loading block, not one per shimmering line |
| Colour | Never the only signal: status and direction also carry an icon, sign or value |
| Contrast | Enforced when a theme is saved, not audited afterwards |
| Clickable elements | Every click target shows the hand cursor; a non-native click target opts in with data- |
The two theming axes#
Resolution order: the brand in view, the organization, the deployment's active skin, then the default. One schema validates every payload for editor, API and renderer. A skin is two generated CSS blocks (light, dark) in one injected style element; a static audit rejects a second one, and the platform admin area always renders the system skin.
| Axis | Set by | Meaning |
|---|---|---|
data- |
The server, from the deployment's active theme | Skin identity |
data- |
The reader's toggle, remembered per browser, defaults to light | Light or dark; the OS colour-scheme preference is not read |
Skins at three levels#
| Level | Owned by | Visible to | Can change |
|---|---|---|---|
| Platform skin | A super admin | Every organization | The full skin; one of them is the site-wide default |
| Organization skin | The org's owner or admin | That organization only | The full skin; wins over a same-named platform skin |
| Brand override | The brand | That brand's surfaces, public share links included | Ink only: accent, text, status, chart series, heat ramps, panel tones; never structure |
A brand override is validated against the merged result, so it cannot save an unreadable combination. Activating and editing skins needs no code: Platform administration.
How to#
Add a built-in skin
- Copy the nearest entry in the built-in theme module.
- Give it a slug (2 to 48 lowercase letters, digits or hyphens) and a Vietnamese and English name.
- Fill in both modes, with 4 to 8 chart series colours and a tooltip background unlike every series colour.
- Meet the contrast checked on save: primary text and button text 4.5:1, sidebar text 3:1 on both gradient ends.
- Run the full gate, then preview and activate it in Appearance, and revert to the default.
Add a themeable token
Rare, and it needs a design owner's agreement.
- Add the token to the base stylesheet's light and dark blocks.
- Add the field to the theme schema and the one payload-to-token mapping function.
- Update every built-in payload and the snapshot tests.
- Keep the theme single-source audit green: every token the renderer emits must exist in the stylesheet.
Move skins between deployments
- In Appearance, tick the skins and export them as a versioned bundle file.
- On the target, choose the file, review the preview and confirm. Each skin returns
imported,renamed(slug collision, numeric suffix) orrejected(failed checks, never written). - Limits: 256 KB per bundle, 20 skins per import; both directions are audited.
Verify a theme change
- Run the full gate: it includes the theme single-source audit and a token-drift baseline that may only shrink.
- Check in a browser, light and dark, with Vietnamese diacritics, empty states and chart tooltips.
- Revert any experimental activation to the default skin.
Common traps#
| Trap | What to do instead |
|---|---|
| Editing the base stylesheet to change a skin | Wrong layer: that stylesheet is the default skin; edit the skin's payload |
| Emitting tokens by hand, or adding a second style element | There is one injection path, and the audit fails the build |
| Forgetting the dark half of a skin | Both modes are required; the schema refuses a half skin |
| A tooltip background equal to a series colour | The server refuses it; pick another background |
| Expecting a PDF export to follow the skin | It does not; PDF output keeps a fixed brand |
Source files#
| File | Covers |
|---|---|
packages/ |
Default skin tokens, type scale, spacing, z-index, motion |
packages/ |
Primitives and their accessibility behaviour |
packages/ |
The 20-row default page size |
packages/ |
Destructive confirm behaviour |
packages/ |
The single theme payload and bundle schema |
apps/ |
Skin resolution, org scope, brand override merge |