Skip to content
MSO CloudDocumentation

Design system and theming

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 --surface-app #f3f5fc
Card surface --surface-card #ffffff
Primary text --text-primary #192039
Muted text --text-muted #62687d
Accent --accent-primary #4d59d2
Success --yng-success #1fb57a
Warning --yng-warning #f4b740
Danger --yng-error #e24c4b
Info --yng-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 / ConfirmDialog, 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.

classpxfont size on line heightgrouptext-caption11 / 16text and controlstext-meta12 / 16text-body-sm13 / 18text-body14 / 20text-body-lg15 / 22text-title-sm16 / 22headingstext-title18 / 26text-title-lg20 / 28text-display-sm24 / 32figurestext-display30 / 39text-hero36 / 38public pages onlytext-hero-lg48 / 51
Every step carries its own line height, so no size needs a separate leading class. The light track is the line height, the bar the font size.

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-chip 6px Badges, tags
rounded-field 8px Inner rows, small tiles
rounded-control 10px Inputs, buttons, switches
rounded-card 14px Cards, panels, table frames
rounded-modal 16px Dialogs, popovers
rounded-pill 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.

z-base0z-raised10z-sticky40z-dropdown45z-overlay50z-modal60z-toast70z-tooltip80Stacking and motion are not themeable; a skin may replace only shadow-card and shadow-card-hover (plus three radii).Motion: duration-fast 150 ms, duration-normal 220 ms, duration-slow 320 ms; the OS reduced-motion setting is honoured.
The stacking ladder, to scale. A fixed order means a tooltip is always above a toast and a toast above a modal.

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-clickable

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-skin The server, from the deployment's active theme Skin identity
data-theme 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

  1. Copy the nearest entry in the built-in theme module.
  2. Give it a slug (2 to 48 lowercase letters, digits or hyphens) and a Vietnamese and English name.
  3. Fill in both modes, with 4 to 8 chart series colours and a tooltip background unlike every series colour.
  4. Meet the contrast checked on save: primary text and button text 4.5:1, sidebar text 3:1 on both gradient ends.
  5. 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.

  1. Add the token to the base stylesheet's light and dark blocks.
  2. Add the field to the theme schema and the one payload-to-token mapping function.
  3. Update every built-in payload and the snapshot tests.
  4. Keep the theme single-source audit green: every token the renderer emits must exist in the stylesheet.

Move skins between deployments

  1. In Appearance, tick the skins and export them as a versioned bundle file.
  2. On the target, choose the file, review the preview and confirm. Each skin returns imported, renamed (slug collision, numeric suffix) or rejected (failed checks, never written).
  3. Limits: 256 KB per bundle, 20 skins per import; both directions are audited.

Verify a theme change

  1. Run the full gate: it includes the theme single-source audit and a token-drift baseline that may only shrink.
  2. Check in a browser, light and dark, with Vietnamese diacritics, empty states and chart tooltips.
  3. 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/ui/src/styles.css Default skin tokens, type scale, spacing, z-index, motion
packages/ui/src/kit.stories.md Primitives and their accessibility behaviour
packages/ui/src/components/data-table.tsx The 20-row default page size
packages/ui/src/components/confirm-dialog.tsx Destructive confirm behaviour
packages/ui/src/theme-schema.ts The single theme payload and bundle schema
apps/web/src/server/themes/ Skin resolution, org scope, brand override merge