App SCSS (core/web/assets/css)
App-owned styles sit beside the Nuxt CSS entries. Theme tokens remain in @tgmc/theme — see packages/theme.md.
Partials
| File | Role |
|---|---|
_variables.scss |
App :root / html[data-theme] for the --portfolio-* tokens, the IBM Plex font-family overrides, and --type-* chrome metrics. Never redeclares theme layout / space / radius / shadow / ratio / role tokens. Colour variables are --portfolio-*-color blends of the theme’s active colours (color-mix() of --theme-*-color) — no hex, no Sass colour values, no old-name aliases |
_mixins.scss |
Mixin-only recipes (portfolio-box-contain, portfolio-soft-surface($mix?), portfolio-type-* / portfolio-eyebrow, portfolio-stack($gap?)) — no selectors |
_globals.scss |
Selectors used on more than one page: .page-content element fit, headings via type recipes, links, eyebrows, tags, .portfolio-hero, phone .button-row, anchor scroll padding, PrimeVue dialog glass (teleported, so it cannot be scoped), motion preferences. Breakpoints via bp-down() / bp-up() only. Page-only rules live in the page sheet; component-only rules in the component sheet. Emitted once via launch — do not @use from pages |
styles.scss |
Thin theme entry (@use 'theme/scss' — document shell lives in theme/core/scss/_layout.scss) |
portfolio-launch.scss |
Entry only: @use variables + globals, and the IBM Plex @font-faces. No selectors (guarded by tests/app-scss-sot.spec.ts) |
Load order
styles.scss→ themeportfolio-launch.scss→@use './variables'(emits CSS) →@use './globals'(emits tag/selector CSS; it@usesmixins) →@font-faces- Standalone page/component
.scss→@use 'mixins' as *(resolved via Vite SassloadPaths→assets/css) — never@use_globals.scssfrom pages (avoids duplicated selectors) - Vue
<style lang="scss">— ViteadditionalDataprepends themenuxt-auto(pkg:@tgmc/theme/scss/nuxt-auto, from@tgmc/nuxt-layer-base’stgmcScssAdditionalData) and app_mixins.scss(absolute path; Vue-only, same gate). Usevar(--portfolio-*-color)/var(--theme-*-color)for colours (see Colour rules for pages and components); do not inject_globals.scss
nuxt-auto forwards theme variables, colors, theme-* color helpers (tokens/_color-fns.scss), and button mixins. Standalone sheets that need helpers @use 'theme/scss/nuxt-auto' as * or @use 'theme/scss/tokens' as * (via Sass loadPaths).
Nuxt/Vite wiring lives in core/web/config-properties/scss-additional-data.ts (loadPaths for theme / app CSS; scssAdditionalData and scssImporters are built from the base layer’s tgmcScssAdditionalData / tgmcScssImporters, and the importer also resolves the theme’s pkg:foundation-sites/... imports), scss-auto-use.ts (re-exports the base layer’s Vue-only gate), and vite-prop.ts. The PrimeVue config (Nora preset → --theme-accent-color) moved to packages/nuxt-layer-ui/src/config/primevue.ts (tgmcPrimeVueConfig()). Theme entry flags: assets/css/styles.scss ($theme-enable-foundation: true, $theme-foundation-mode: 'layout'; PrimeVue is Nora styled mode with no Sass layer — see theme.md § Third-party layers). Contract tests: core/web/tests/app-scss-sot.spec.ts, core/web/tests/vite-prop-scss-inject.spec.ts, core/web/tests/scss-pkg-importer.spec.ts, and theme scss-color-fns.spec.ts (nuxt-auto forward) and foundation-css-equivalence.spec.ts.
Naming
- App props:
--portfolio-*only. Colour variables are--portfolio-<stem>-color(colour system, spec rule 4); non-colour ones keep their names (--portfolio-space,--portfolio-stack-gap*,--portfolio-surface-mix,--portfolio-background-{image,repeat,size,position,attachment,blend-mode},--portfolio-particle-shadow-strong) - A colour variable holds only
var(--theme-…-color)/var(--portfolio-…-color),color-mix()of them andtransparent— no hex,rgb(),hsl()or Sass$(rule 6). Guard:core/web/tests/colors-scss.spec.ts - The old names (
--portfolio-rose,--portfolio-primary,--portfolio-depth-custom…) are gone: they were aliases until colour system Task 8 removed them (archived intheme/core/scss/_archive/2026-09-29-color-aliases/). The mapcore/web/shared/portfolio-color-names.tsstays for the codemod, the guard (an old name is refused) and the stored Background → Custom key migration - Do not shadow theme names (except the documented coral → accent bridge)
--portfolio-coral-colorisvar(--theme-accent-color);--portfolio-teal-coloris the theme’s success colour (dark: blended with paper to keep today’s depth) — do not redeclare hex in web--portfolio-rose-colorisvar(--theme-link-color)(the theme’s builder-computed link ink) and--portfolio-rose-strong-coloran OKLab mix of it toward--theme-text-color(85 % light / 50 % dark) — colour-system rule 3, 2026-10-05- There is no teal fill pair any more: the /about résumé is
UiButton severity="success", so--portfolio-teal-fill-color/--portfolio-on-teal-colorwere removed (archived intheme/core/scss/_archive/2026-10-14-final-review/) --portfolio-ivory-color/--portfolio-ink-colorare the active paper / ink (dark ink: ink with 3% paper, today’s text colour)- Preset / custom background roles (
--portfolio-{primary,secondary,accent}-color,--portfolio-background-{primary,secondary,accent}-colorand their-{light,dark}-colorper-mode names,--portfolio-depth-custom-color) are written at runtime by Preferences (shared/preferences/paint.ts, throughusePersonalization); untouched they fall back to the theme colours
Type recipes
Theme emits --font-family-display|title|header (Sass $header-font-family may be empty). The app binds those roles in _variables.scss so recipes never resolve to an empty family: --font-family-display is the Barlow Condensed stack, --font-family-title and --font-family-header alias it, --font-family is IBM Plex Sans and --font-family-mono is IBM Plex Mono.
Fonts: Barlow Condensed 600–800 (display: h1, h2, door labels, monogram), IBM Plex Sans 400 / 600 (text), IBM Plex Mono 400–600 (code, eyebrows, meta). All faces load from Fontsource on jsDelivr with font-display: swap (portfolio-launch.scss); the theme’s own tokens/custom/_fonts.scss faces (Bebas, ‘Barlow Condensed ExtraBold’) are not used by the app. Contract: core/web/tests/fonts.spec.ts.
Chrome metrics live on :root as --type-eyebrow-* and --type-meta-*. Mixins apply the ladder:
| Role | Mixin | Family |
|---|---|---|
| Primary page title | portfolio-type-display |
--font-family-display |
| Section title | portfolio-type-title |
--font-family-title |
| Eyebrow / kicker | portfolio-type-eyebrow (alias portfolio-eyebrow) |
mono + wide tracking |
| Meta / label / tag | portfolio-type-meta |
mono + tighter tracking |
.portfolio-page h1 / h2 and shared eyebrow/tag selectors consume these from _globals.scss. Pages and components @include the same mixins instead of inventing one-off font-family rules. See CONCEPTS: Type recipe / Chrome type tier. Contract: core/web/tests/type-recipes.spec.ts.
Color SoT hygiene
- Measure before delete. Run
node scripts/measure-app-scss.mjs— it emitsscss_linesandduplicate_color_sot(starter twin map + exact hex / JS const overlaps). Coral is an accent bridge, not a static theme-primary hex twin. - Delete only proven twins. Rebind call sites to theme CSS vars or Sass tokens; do not invent coral as a static hex twin.
- Blended chrome. The atmosphere (
--portfolio-rose-color,-haze-*,-particle-*,-grid-*,-rule,-teal,-coral,-ink,-ivory) iscolor-mix(in srgb, …)(rose-strong:in oklab) of the theme’s active paper / ink / primary / accent / success and the link / text / success-background roles, so it follows mode switches and Style Studio edits live. No hex, no Sass colour values. - JS recipe parity.
shared/portfolio-chrome.tsholds the recipe table (PORTFOLIO_CHROME_BLENDS), renders it to CSS (portfolioBlendCss) and resolves it (getPortfolioChrome(mode, inputs?)).portfolio-chrome.spec.tschecks that_variables.scssdeclares exactlyportfolioBlendCss(recipe)for each colour and mode, and that the JS values match the Sass dumpassets/css/export/portfolio-chrome-dump.scss(the same blends with Sasscolor.mixfrom the theme’s default colours). UI keepsvar(--portfolio-*-color). - CSS-only (no JS mirror): the translucent
--portfolio-rule-color(ink 21%) and--portfolio-grid-line-color(rose-strong 26% light / rose 50% dark), and the dark--portfolio-particle-shadow-strong(0 0 10pxrose 70%). - Personalization. FOUC +
buildBrandTokens+ paper constants use@tgmc/themeColor/themeColors(ivory/ink viaportfolio-chrome) — see personalization.md.
Contract tests: core/web/tests/app-scss-sot.spec.ts, core/web/tests/portfolio-chrome.spec.ts. Measure harness: scripts/measure-app-scss.mjs.
Atmosphere blend table
mix(a p, b) = color-mix(in srgb, var(--theme-a-color) p%, var(--theme-b-color)), with the mode’s active colours (light: paper #faf6f3, ink #0f0908, primary #d9531d, accent #1b95c7, success #146060; dark: paper #0f0908, ink #faf6f3, primary #be1c26, accent #19aca3, success #1f8b8b). Before is the pre-blend Sass value (oxblood / brand mixes), after the blend with the default theme. ΔE is the OKLab distance ×100 computed from the displayed hex values (≈ 2 is a just-noticeable difference; translucent values composited over the mode’s paper at the displayed alpha). Tuned so the default atmosphere stays close to the old look, except the light rose family, which is tuned for contrast (below); the recipes live in shared/portfolio-chrome.ts.
--portfolio-…-color |
Light blend (:root) |
Light before → after | ΔE | Dark blend (html[data-theme='dark']) |
Dark before → after | ΔE |
|---|---|---|---|---|---|---|
rose |
link (2026-10-05; was mix(primary 70%, ink) #9c3d17) |
#c63549 → #883412 |
14.1 | link (was mix(primary 56%, ink) #d87c80) |
#dc7b88 → #e96a72 |
4.2 |
rose-strong |
oklab(link 85%, text) (was mix(primary 60%, ink) #883515) |
#ac1922 → #762f15 |
11.2 | oklab(link 50%, text) (was mix(primary 30%, ink) #e8b5b5) |
#ebb3bb → #f3afae |
2.0 |
haze-1 |
mix(accent 10%, mix(primary 30%, paper)) |
#e0bdbf → #dbc0b5 |
1.98 | mix(primary 49%, paper) |
#621c25 → #651217 |
2.08 |
haze-2 |
mix(accent 8%, mix(primary 23%, paper)) |
#e6c9ca → #e1ccc2 |
1.73 | mix(primary 10%, paper) |
#21090d → #210b0b |
0.83 |
haze-3 |
mix(accent 6%, mix(primary 16%, paper)) |
#ebd5d5 → #e8d8d0 |
1.27 | mix(primary 12%, paper) |
#25070e → #240b0c |
1.34 |
haze-4 |
mix(accent 4%, mix(primary 10%, paper)) |
#f1e2e1 → #eee2dd |
0.72 | paper |
#0b0204 → #0f0908 |
4.07 |
particle-strong |
mix(primary 71%, ink) |
#ac1922 → #9e3e17 |
6.02 | mix(primary 53%, ink) |
#ec7c83 → #da8286 |
3.18 |
particle-mid |
mix(accent 31%, primary) |
#a46169 → #9e6752 |
4.27 | mix(primary 56%, ink) |
#dc7b88 → #d87c80 |
1.42 |
particle-soft |
mix(accent 6%, mix(primary 19%, paper)) |
#e9d1d2 → #e7d3ca |
1.41 | mix(ink 97%, paper) |
#f3efec → #f3efec |
0 |
grid-glow |
mix(accent 4%, mix(primary 12%, paper)) |
#efdedd → #eddfd9 |
0.74 | mix(primary 65%, paper) |
#7e212e → #81151c |
2.34 |
grid-line |
rose-strong 26% over transparent | #ac1922/26% → #883515/26% |
2.43 | rose 50% over transparent | #dc7b88/50% → #d87c80/50% |
0.79 |
rule |
ink 21% over transparent | #181211/22% → #0f0908/21% |
0.12 | ink 21% over transparent | #f3efec/22% → #faf6f3/21% |
0.32 |
teal |
success |
#146060 → #146060 |
0 | mix(success 87%, paper) |
#1b7a7a → #1d7a7a |
0.09 |
coral |
accent |
#1b95c7 → #1b95c7 |
0 | accent |
#19aca3 → #19aca3 |
0 |
ink |
ink |
#0f0908 → #0f0908 |
0 | mix(ink 97%, paper) |
#f3efec → #f3efec |
0 |
ivory |
paper |
#faf6f3 → #faf6f3 |
0 | paper |
#0f0908 → #0f0908 |
0 |
Where the ΔE budget (≤ ~3) is not met:
- Rose / rose-strong follow the link ink (rule 3, 2026-10-05).
roseis--theme-link-color—buildLinkTokensmoves the primary’s lightness until it reads ≥ 4.5:1 on page, surfaces, variant and its own 12 % / 16 % washes, for any pick and paper / ink (the old blends were never checked: random picks reached 3.75:1, 3.08:1 on the nav wash) — androse-strongmixes it toward the text colour in OKLab, which keeps it ≥ 4.5:1. The ΔE above is the owner-approved change (light crimson-orange → deeper brick, dark coral-pink → rose-red). - Light rose / rose-strong (by design, before rule 3). The old values are crimson (oxblood family); since colour-system Task 3 the light primary is orange (
#d9531d), and the owner accepted that the rose family follows the primary. The light recipes are darker than the closest blend (the closest,mix(primary 87%, ink), only reached 4.12:1 on the surface) so rose text passes WCAG AA everywhere it is painted — see the contrast table below. - Light particle-strong / particle-mid. The crimson originals cannot be reached from paper / ink / primary / accent / success (every blend stays on the orange side); these are the closest blends.
- Dark haze-4. The old value (
#0b0204) is darker than dark paper, and every blend is at least as light as paper;paperis the closest.
Rose text contrast (WCAG, default theme)
rose is link / hover text (_globals.scss, AppPrimaryNav on a 12% rose tint, gallery tabs on a 4% text wash; UiButton’s outlined hover border reads --theme-link-color, the same colour, and its label is the primary ink); rose-strong is link hover and the active work filter text (on a 16% rose tint, pages/work). Tints are composited over paper and over the surface (the header’s 92% surface glass is ≈ surface). Guarded by portfolio-chrome.spec.ts (≥ 4.5:1 on every row, both modes) and, for all 21 presets and 300 random paper / ink pairs, theme/core/tests/derived-roles-contrast.spec.ts.
| Background | Light rose #883412 |
Light rose-strong #762f15 |
Dark rose #e96a72 |
Dark rose-strong #f3afae |
|---|---|---|---|---|
| paper | 7.67 | 8.93 | 6.37 | 10.87 |
| surface | 6.77 | 7.88 | 5.97 | 10.19 |
| surface variant | 5.95 | 6.93 | 5.71 | 9.75 |
| soft surface 88% | 6.89 | 8.03 | 6.02 | 10.28 |
| text 4% wash on paper / surface | 7.08 / 6.24 | — | 5.97 / 5.48 | — |
| rose 12% tint on paper / surface | 6.33 / 5.60 | — | 5.58 / 5.11 | — |
| rose 16% tint on paper / surface | — | 6.88 / 6.11 | — | 8.97 / 8.24 |
| worst case | 5.60 | 6.11 | 5.11 | 8.24 |
Before this tuning the light worst cases were 3.54 (rose on the 12% tint over the surface) and 4.46 (rose-strong on the 16% tint over the surface); at the pre-blend base, light rose #c63549 was 4.88:1 on paper and 4.30:1 on the surface.
Only rose, rose-strong, rule and teal are painted today (links, hairlines, teal signals); the haze / particle / grid-glow names have no consumers and are kept for the atmosphere.
Colour rules for pages and components
Layouts, pages and components (core/web/app/**/*.{vue,scss}) follow spec rule 5: they use colour variables and never define colours.
Names to use. Colour var()s name one of these:
- A theme colour,
--theme-*-color. Examples:--theme-text-color,--theme-surface-color,--theme-border-strong-color,--theme-link-color,--theme-focus-ring-color,--theme-primary-color,--theme-on-primary-color, the status colours--theme-success-color/--theme-error-color(and their-inkroles), the alpha steps--theme-ink-a24-color, and the fixed per-mode variations such as--theme-paper-dark-color. - An app colour,
--portfolio-*-color. Examples:--portfolio-rule-color,--portfolio-rose-color,--portfolio-teal-color,--portfolio-primary-color. - A palette name the owner keeps:
--red-color…--magenta-color, and thepalettelist intheme/core/src/color-rename-map.json.
The name must be declared: by the theme’s :root (theme/core/scss/globals/_root.scss), by _variables.scss, or by the runtime writers (RUNTIME_COLOR_TOKEN_NAMES, --portfolio-depth-custom-color). A typo such as --theme-primry-color fails the guard.
Text uses -ink roles. color:, -webkit-text-fill-color: and SVG text fill: (a rule for text or a …label) never read a main variation — --theme-primary-color, --theme-secondary-color or --theme-accent-color, not even as a var() fallback or a color-mix() argument: they reach only 3:1 (fills, borders, graphics). Brand-coloured words use --theme-primary-ink-color, secondary-coloured words --theme-secondary-ink-color (both ≥ 4.5:1 on page, surface and variant; a color-mix() that tints text mixes from the ink role); status text uses --theme-<status>-ink-color; links --theme-link-color. Fills, borders, text-decoration-color, accent-color and outline stay on the main variation. Guarded by the “text never paints a 3:1 main variation” tests (core/web/tests/colors-scss.spec.ts, core/admin/tests/colors-scss.spec.ts; engine mainVariationTextProblems in core/web/tests/support/colors-scss-guard.ts; the theme layer: theme/core/tests/text-roles.spec.ts). The allowlist counts exact occurrences; its one entry is the architecture diagram’s edges (currentColor for strokes and arrowheads, not text). The diagram’s SVG group labels and the /styles column labels sit on tints, so they mix --theme-secondary-ink-color toward --theme-text-color (75 % and 60 % ink), checked for every preset in core/web/tests/secondary-ink-sites.spec.ts.
Never fade text with opacity. Use --theme-text-secondary-color (or another role). Allowed: disabled states, @keyframes, and decorative non-text layers marked /* opacity: decorative … */ (guard: core/web/tests/faded-text.spec.ts).
A tint is a color-mix() of those names with transparent, or of two of those names. Old names such as --text-color, --primary-color, --portfolio-rule and --focus-ring are gone (colour system Task 8): the stylesheet no longer declares them, so they paint nothing, and the guard refuses them.
No literals. No hex, no rgb() / hsl(), no oklch() / oklab() / lab() / lch() / hwb() / color() (a color-mix() of the names above is fine), no named colours, and no Sass $ colour values: no top-level $x: <colour> and no $x passed to an @include. This applies in style blocks and .scss files, including shadows, gradients, masks, filter: drop-shadow() and SVG stops. It also applies to inline styles: a static style="…" and the string values of a :style object or array literal (div(style="color: white") and :style="{ color: 'black' }" both fail).
When a design needs a colour that no name covers, use the nearest variation (R-T5e): ink, paper, a main colour or a status colour, with alpha where needed. Two examples:
- Black that must stay black in both modes (a video letterbox, a mask, a darkening mix) becomes
var(--theme-paper-dark-color). - The code window’s traffic-light dots are decoration, not status, so they use the owner-kept palette:
--red-color,--amber-colorand--green-color(owner decision).
No colour variables. A component declares no colour custom property. It points at the theme or app name directly.
- Where the colour is data, it is set inline on the property itself. For example, a Style Studio palette swatch is
background: <hex> !important, and aUiImagedominant colour and its ink are set asbackground-colorandcolor. - Custom properties are set in SCSS, never inline: the guard refuses every inline
:style="{ '--x': … }"/style['--x'] = …. Non-colour hooks such as--ui-image-zoom(set by a host sheet) and--work-card-media-widthare declared in SCSS and are fine.
Data, not styling. Hex strings that are data are allowed only when they are listed, with a reason and an exact occurrence count, in the guard’s APP_DATA_LITERALS (a second, painted use of the same hex fails). Data here means picker values, contrast-maths fallbacks and documentation specimens.
Codemod. node scripts/rename-color-vars.mjs <dir>… rewrites every var(<old> to var(<new>.
- It reads its map from the theme
renamesand fromshared/portfolio-color-names.ts. - It matches exact names only, so
--primary-colornever matches inside--primary-color-inverted. - It prints a per-file count and skips
components/AnalogClock.vue(by path),components.d.ts,_archive/,*.generated.scssand the guard specs whose fixtures use old names on purpose. node scripts/rename-color-vars.mjs --check core theme packagesreports 0 since Task 8 (guarded by a node test).--checkreports without writing, and exits 1 if any old name remains (2 without a directory).- Tests:
scripts/rename-color-vars.test.mjs.
Guard. core/web/tests/colors-scss.spec.ts, in the “pages, layouts and components” block, scans every .vue file (style, template and script) and every .scss file under core/web/app. components/AnalogClock.vue is excluded by path: it is unreferenced and the owner leaves it alone. The guard fails on three things:
- a literal
- a declared colour variable
- a
var()of an old or undeclared colour name
core/admin (Task 6). core/admin/app/** and the admin global sheet (core/admin/assets/css/admin.scss) follow the same rules via core/admin/tests/colors-scss.spec.ts, which imports the matching engine from core/web/tests/support/colors-scss-guard.ts (R-T6b) instead of a second copy of it — only the package-specific inputs (declared names, palette, non-colour var pattern, data-literal allowlist) differ. Admin declares no colour custom properties of its own: every admin colour points straight at a --theme-*-color name (R-T6a — a --web-*-color family is reserved for a colour genuinely shared across admin pages that isn’t already a plain theme role; none exists yet, so none is declared). Admin’s pre-rename names (--surface-border, --surface-card, --primary-color, --border-strong, --link-color, --focus-ring, --surface-variant, --border-color, --surface-color, --success-ink, --warning, --danger-ink, --text-color-secondary) are gone; AdminNav, AdminDatabaseSelector, the CDN and Media pages, and admin.scss now reference --theme-border-color, --theme-surface-color, --theme-primary-color, --theme-border-strong-color, --theme-link-color, --theme-focus-ring-color, --theme-surface-variant-color and --theme-text-secondary-color directly, with no hex fallback (the codemod renames var( references only, so every literal fallback was removed by hand).
Buttons in SFC styles
_nuxt-auto.scss forwards the theme tokens, so a component can @include button-flat / button-flat-secondary and use $button-flat-context (a button in a form, search or field group is flat; standalone CTAs keep the gradient). UiButton.vue does this in its unlayered scoped rule. Rules: Buttons: flat and gradient.
Components
Pages use the Ui* wrappers (PrimeVue underneath) wherever one exists — owner decision 2026-10-14: “Utilize the Ui and PrimeVue components.” A page styles only the component root class (the root carries the page’s scope): position, size, margins. Padding, min-height, border, fill, type, hover and focus come from the component. The replaced page rules are archived in theme/core/scss/_archive/2026-10-14-ui-components-pages/; core/web/tests/ui-components-pages.spec.ts guards the sweep.
| Page | Was | Now |
|---|---|---|
/ (AppSplash) |
native checkbox | UiCheckbox (Task 11) |
/about |
portrait img |
UiImage (:aspect-ratio from the portrait size) |
/about |
a.about-cv__resume teal chips, a.about-cv__contact |
UiButton.about-cv__resume(:href, download, severity="success") (UiButton paints the success fill, see below), contact UiButton outlined |
/about, /gallery |
UiButton(as="a", :href …) |
UiButton(:href …) — href / to render the link; no as |
/ai-lab |
textarea#ai-lab-idea |
UiTextarea(input-id="ai-lab-idea", :maxlength="240", :rows="5", required); the submit is flat by context (form) |
/code |
button.code-reader__step + inline SVG chevrons |
UiButton icon-only (chevron-left / chevron-right), outlined secondary, still 44px square |
/code |
button / a.code-reader__action (Copy, View source) |
UiButton Copy (icon="copy", flat) in .code-reader__actions(data-field-actions); View source UiButton(:href) outlined |
/gallery |
button.gallery-grid__open |
Each grid tile is one native button (GalleryGrid); the full view’s controls are UiButtons (GalleryViewer) — gallery redesign 2026-10-19, the feed dialog’s Back button is gone |
/gallery |
span.gallery-grid__badge, span.gallery-grid__platform |
UiTag secondary (now the tile tags in GalleryGrid) |
/work/[slug] |
ul.tag-list > li |
li > UiTag(:value="technology", severity="secondary") |
/process |
article.decision-card |
UiCard.decision-card(role="article"); the body is UiCard’s default slot (UiCard maps it into PrimeVue Card’s #content); the split grid sits on .decision-card__layout; headings stay h2 |
/media-player |
button Play / Pause |
UiButton (play, pause icons) |
admin /admin/blog/* |
UiButton(as="a", href=…) |
UiButton(href=…) |
Filled status UiButtons (severity success / warn / danger / info, not outlined / text / link) paint the theme’s status fill in UiButton’s own unlayered rule: background and border --theme-<role>-hue-color, label --theme-paper-color (≥ 4.5:1 by construction, as the theme’s pv-solid-tone); on hover / focus the fill stays and the label underlines. That covers every branch, links included. PrimeVue’s unlayered .p-button-success reads --p-button-success-background, which is undefined on a page that mounts no PrimeVue Button (only links), so before Task 16 such links had no fill and /about repainted its résumé links (&__resume.p-button[href], now removed and archived). Guards: core/web/tests/ui-button-severity-fill.spec.ts; live check in core/web-e2e/src/e2e/ui-audit.cy.ts (light and dark).
UiCard’s default slot is the card body on both stacks: under PrimeVue it is mapped into Card’s #content (after a named #content, if both are given); core/web/tests/ui-card.spec.ts mounts the real PrimeVue Card.
Shared components (Task 16)
The shared components follow the same rule. The replaced rules are archived in theme/core/scss/_archive/2026-10-14-ui-components-shared/, and core/web/tests/ui-components-shared.spec.ts guards the sweep.
UiSelectButton (packages/nuxt-layer-ui/app/components/ui/UiSelectButton.vue, part of the ui layer kit) is the segmented single choice: PrimeVue SelectButton (in the theme’s PrimeVue component list, theme/core/src/primevue.ts, and the layer’s TGMC_PRIME_COMPONENTS), else a role="group" of button.p-togglebutton[aria-pressed]. Props: options, optionLabel ('label'), optionValue ('value'), optionDisabled, ariaLabel; v-model of the value; #option="{ option }" replaces a segment’s content (keep the label text: it is the accessible name). Every segment is a 44px target; the pressed one has the variant surface and a link-colour underline (not colour alone); hover underlines; focus is the theme ring. Counts stay in the label (“Packages · 12”). Its box sits in :where(), so a consumer class (for example hiding a facet at a breakpoint) wins.
| Component | Was | Now |
|---|---|---|
AppBrowseToolbar |
segmented button[aria-pressed] (view, group, kind) |
UiSelectButton per facet (counts in the label; a zero count disables the option unless it is selected) |
AppBrowseToolbar |
input(type="search") |
UiInputText(type="search", autocomplete="off") in the labelled Search field (44px, 16px text) |
AppBrowseToolbar |
button.browse-toolbar__clear |
UiButton(label="Clear filters", severity="secondary"), flat by role="search" |
AppOrbitStage |
four background button[aria-pressed] |
UiSelectButton(v-model="backgroundModel", aria-label="Background mode"), written through setBackground |
AppOrbitStage |
img.orbit-stage__card-img |
UiImage(aspect-ratio="16 / 9") for rasters, UiSvgImg for SVG diagrams |
AppEvidenceExamplesDialog |
ul.tag-list > li text |
li > UiTag(severity="secondary") |
GalleryInfoPanel |
(was GalleryFeedCard, removed 2026-10-19) ul.tag-list > li text |
ul.gallery-info__tags > li > UiTag(severity="secondary") |
AppWorkCard |
.work-card__tech li pills |
li > UiTag(:value="technology", severity="secondary") |
AppStyleStudio |
button.style-studio__setup, __setup-delete, __undo-btn |
UiButton outlined secondary (swatches + name), icon-only trash-2 text button (touch-target mixin, 44px square); Undo is the kit’s UiUndoNotice |
AppStyleStudio |
pack input(type="radio") chips |
UiRadio covering the chip, invisible (the chip is the radio’s face; arrow keys and focus ring kept) |
AppStyleStudio |
role button[aria-pressed] group |
UiSelectButton(option-value="key") with the role’s colour dot in #option |
AppPrimaryNav |
button.primary-nav__personalize + inline SVG |
UiButton(icon="contrast", variant="text"), kept a 44px square |
With every tag list on UiTag, the global .tag-list li chip in assets/css/_globals.scss is gone (.tag keeps it), and /work/[slug] no longer resets it.
Kept hand-rolled on purpose:
- Whole-card links —
docs-card, blog cells,AppWorkCard, the splash doors: the design system’s one-link card.UiCardhas no link mode. - The
/codevertical snippet tablist — two-line tabs;UiTabsis horizontal with one-line labels. - Native
<select>pickers (the/codesnippet picker on phones, the browse toolbar’s Group / Filter pickers on tablets and phones) — the repo touch rule. - The gallery full view’s modal container (
GalleryViewer) — a full-screen stage, one piece at a time with a resizable side panel, with its own inert / focus handling (useInertOutside);UiDialogis a centred panel. (It replaced the scroll-snap feed on 2026-10-19.) - The Menu and PageNav disclosure toggles — disclosure buttons with their own expanded state and layout.
- Style Studio
.btnpreviews — they preview the raw button classes themselves.
When to add a mixin vs a global selector
- Mixin (
_mixins.scss): same recipe in ≥2 sheets, or thinning launch chrome that pages also need via@include. - Selector (
_globals.scss): shared HTML tags / classes that should load once on every page (headings, default links,.page-contentcontainment, eyebrows, tags). - Prefer a mixin when Vue scoped styles need the recipe without emitting another global rule.
Layers, units and breakpoints
assets/css is layer 2 of five (theme → app global → layout → page → component). Pages and components are scoped; site.scss is the only layout sheet. Units are relative (rem / em / % / dvh / container units) — px only for hairlines, focus rings, shadows, blur, the --touch-target / --type-min floors and /* units: scene */ sheets. Breakpoints come from bp-up() / bp-down() (em, range syntax) or container queries; never raw min-width / max-width. Fluid type is clamp(min, rem + vw, max) (never vw-only; guarded by tests/ui-floors.spec.ts); headings use --type-display-size / --type-h2-size / --type-h3-size / --type-h4-size / --type-lede-size from assets/css/_variables.scss. Policy and guards: theme.md § Style layers and units; the 768px pitfall: solutions/ui-bugs/breakpoint-overlap-at-768px.md.