Starlight_Lancher/.agents/skills/oiloil-ui-ux-guide/references/extended-dimensions.md

Extended Token Dimensions

The original token model (color / font / radius / spacing / shadow / motion) is enough to describe a sterile design system. To capture the things that actually distinguish style families from each other in real product UI, the spec also tracks four additional dimensions:

1. containerStrategy — how container boundaries are expressed
2. iconSystem — which icon set, weight, and treatment
3. decoration — gradients, textures, motifs (mostly for marketing and hero surfaces)
4. locale — primary language + secondary supported languages

Each of these is a real visual decision. Skipping them is the reason the original preview template made modern-minimal and warm-content look identical when rendered.

---

1. containerStrategy

How do containers (cards, panels, list rows, sections) visually separate from each other?

Value	What it means	Implications
border	1px borders around containers, often with a slight surface tint	The default of most SaaS UI. Reads as "designed system".
tinted-surface	Container surface color is offset from page bg (lighter or darker), no border	iOS 14+ Health, many fintech apps. Feels softer, more depth.
elevation	No border. Soft shadow does the work.	Material, macOS. Reads as physical, "objects on a desk".
divider	Containers don't have visible boundaries; horizontal/vertical dividers separate sections within	Editorial, list-heavy interfaces. Quiet.
none	Pure spacing and typography do the grouping work	Brutalist, manifesto pages, premium-luxury heroes.

A project may pick one strategy globally and override per-surface (e.g. tinted-surface everywhere except dashboard tables which use divider).

2. iconSystem

iconSystem:
  set: lucide | phosphor | heroicons | carbon | tabler | material | brand-custom
  weight: thin | regular | bold | filled         # set-dependent
  treatment: monochrome | two-tone | brand-tinted

Notes:

• lucide — the modern default; clean, monoline, regular weight. Works in almost any family.
• phosphor — has 6 weights; great for playful (bold/filled) and editorial (thin/regular).
• heroicons — Tailwind ecosystem; outline + solid. Solid is heavier; pick on purpose.
• carbon — IBM design system. Reads enterprise.
• tabler — close to lucide visually but with more variety. Good for dense tech-cyberpunk UI.
• material — Google. Carries Material's voice; usually only correct for Android-leaning products.
• brand-custom — when the brand has a proprietary set; default for established brands.

The treatment matters more than people think:

• monochrome — single color (usually text color or muted), recedes.
• two-tone — accent + neutral, draws attention. Often playful / warm-content.
• brand-tinted — uses primary at a lower alpha. Works in modern-minimal and tech-cyberpunk.

3. decoration

decoration:
  gradients: none | subtle | expressive
  textures:  none | noise | dot-grid | paper | scan-lines
  motifs:    none | geometric | illustration | photography | data-viz

Definitions:

• gradients
  • none — no decorative gradients. Solid color blocks only.
  • subtle — at most one gradient per page (typically hero background or a single accent button).
  • expressive — gradients are part of the visual language (multiple per page, animated where appropriate).
• textures
  • noise — film grain / noise overlay; widely used in playful and brutal.
  • dot-grid — engineering / blueprint feel; common in tech-cyberpunk.
  • paper — warm canvas texture; warm-content, editorial, premium-luxury.
  • scan-lines — CRT / terminal aesthetic; only tech-cyberpunk and very deliberate brutalism.
• motifs — what's the secondary visual language alongside copy?
  • geometric — abstract shapes (circles, blobs, strokes) used as decoration.
  • illustration — characters / scenes; in family for playful and warm-content.
  • photography — used heavily in premium-luxury, editorial, warm-content.
  • data-viz — charts / sparklines as decoration; tech-cyberpunk, modern-minimal SaaS.

Decoration is per-surface: marketing pages may go expressive + illustration, while the dashboard stays none / none / data-viz.

4. locale

locale:
  primary: zh-CN | zh-TW | en | ja | ko | ...
  secondary: [list of supported locales]

Why this is a token decision, not a runtime concern:

• Font shortlist depends on language. Plus Jakarta Sans is great for Latin; for zh-CN you need a CJK-capable font (Noto Sans SC, Source Han Sans, PingFang fallback). For ja add Noto Sans JP / Hiragino. The skill should propose locale-appropriate fonts in Phase 3, not generic Latin-only candidates.
• Line-height and font-size baselines differ. CJK body needs larger line-height (1.7+) to be comfortable; Latin can do 1.5. Hard-coding 1.5 leaves CJK text feeling cramped.
• Letter-spacing. Negative letter-spacing on display headings looks great in Latin and bad in CJK.
• Demo content. A user looking at an English Active users 2,847 dashboard cannot judge how their actual Chinese product will feel. The preview must render in the project's primary language.

When secondary is non-empty, the chosen body font must support all listed scripts (or the spec must define a font fallback stack).

---

Per-family defaults

Each style family has a default starting point across the four extended dimensions. The user can always override.

modern-minimal

Dim	Default	Compatible alternatives
containerStrategy	border	tinted-surface, divider
iconSystem	lucide regular monochrome	tabler, heroicons
decoration.gradients	none	subtle (hero only)
decoration.textures	none	dot-grid (engineering brand)
decoration.motifs	data-viz (dashboard) / geometric (marketing)	—
locale	as project	—

editorial

Dim	Default	Compatible alternatives
containerStrategy	divider or none	border (only for code blocks / sidebars)
iconSystem	phosphor thin or regular monochrome	lucide
decoration.gradients	none	—
decoration.textures	paper	none
decoration.motifs	photography	illustration (for cover art)
locale	as project; serif body fonts must support locale	—

brutal

Dim	Default	Compatible alternatives
containerStrategy	border (thick, 2-4px)	none
iconSystem	brand-custom ASCII / Unicode glyphs	tabler bold, system emoji ironically
decoration.gradients	none (use color blocks)	—
decoration.textures	noise or paper	scan-lines
decoration.motifs	geometric (raw shapes)	—
locale	locale-agnostic; mono fonts must support locale	—

playful

Dim	Default	Compatible alternatives
containerStrategy	tinted-surface or elevation	border (thin, soft color)
iconSystem	phosphor bold or filled, two-tone	heroicons solid
decoration.gradients	expressive	subtle
decoration.textures	noise	paper
decoration.motifs	illustration	geometric
locale	leans toward rounded fonts in any locale (Nunito ZH, Noto Sans Rounded, etc.)	—

premium-luxury

Dim	Default	Compatible alternatives
containerStrategy	none or divider	—
iconSystem	optional; phosphor thin monochrome if used; brand-custom preferred	—
decoration.gradients	none	subtle (very dark/very light)
decoration.textures	paper or none	metallic foil (rare)
decoration.motifs	photography (full-bleed editorial)	none
locale	serif body; for CJK, prefer Source Han Serif / Songti family	—

tech-cyberpunk

Dim	Default	Compatible alternatives
containerStrategy	tinted-surface (dark)	elevation (with glow not shadow)
iconSystem	tabler or carbon monochrome	lucide
decoration.gradients	subtle (mesh / neon glow)	expressive (deliberate, neon)
decoration.textures	dot-grid or scan-lines	noise (film-grain)
decoration.motifs	data-viz	geometric (terminal glyphs)
locale	mono fonts must support locale; for CJK: JetBrains Mono + Noto Sans Mono CJK	—

warm-content

Dim	Default	Compatible alternatives
containerStrategy	tinted-surface	border (warm gray, very low contrast)
iconSystem	phosphor regular two-tone	lucide
decoration.gradients	none	—
decoration.textures	paper	none
decoration.motifs	illustration	photography
locale	warm serif body; CJK: Source Han Serif / Noto Serif CJK	—

brand-driven

All four dimensions derive from brand assets:

• containerStrategy — read from existing brand UI; if brand has cards-with-shadows, use elevation; if brand never uses borders, use none. Look at the brand site's UI patterns.
• iconSystem — brand-custom if the brand has a set; otherwise pick a neutral one (lucide) and document the choice.
• decoration — extract from brand collateral. If brand uses noise overlay everywhere, use noise. If brand never uses gradients, set none.
• locale — primary = brand's primary market language. Secondary = whatever the brand publishes in.

If the brand has not made these decisions explicitly, the consultant's job is to make them and write them into design-spec.md so the brand book is extended, not replaced.

---

How these dimensions feed into the preview template

When design-config.js is written for the preview template:

window.__DESIGN_CONFIG__ = {
  mode: "full",
  // ... existing fields ...
  containerStrategy: "tinted-surface",
  iconSystem: { set: "phosphor", weight: "regular", treatment: "two-tone" },
  decoration: {
    gradients: "subtle",
    textures: "paper",
    motifs: "illustration"
  },
  locale: { primary: "zh-CN", secondary: [] }
};

The template (Commit 2) provides switchers for each so the user can A/B inside one config without rewriting it.

How these dimensions feed into the business mockup

The Phase 4b business mockup MUST honor every one of these dimensions. See references/business-mockup-contract.md.