On this page

Layout & theming

Theme released

The theme as an attribute: light, dark, or the system's own answer.

Import@pacit/components/theme
Selector[pctTheme]

No APG pattern applies, and none is invented — the reasoning is under Accessibility ↓

A dark island: one attribute, every token below it flips.

import { Component } from '@angular/core';
import { PctButton } from '@pacit/components/button';
import { PctTheme } from '@pacit/components/theme';

/** The directive only spells the attribute — the cascade does the theming. */
@Component({
  selector: 'demo-theme',
  imports: [PctButton, PctTheme],
  styles:
    'section { background: var(--pct-surface); color: var(--pct-text); border: 1px solid var(--pct-border); border-radius: 8px; padding: 16px; display: grid; gap: 8px; justify-items: start; }',
  template: `
    <section pctTheme="dark">
      <p>A dark island: one attribute, every token below it flips.</p>
      <button pctButton variant="soft" size="sm">Reads the island</button>
    </section>
  `,
})
export class ThemeDemo {}

theme.demo.ts — the same file runs here and is highlighted under Code

Start here

Usage

One import per component, and the shortest possible use — the package itself is installed once, on the start page.

Import this component

import { PctTheme } from '@pacit/components/theme';

Exported	What it is
`PctThemeName`type`'light' \| 'dark'`	The two themes the shipped skin keys its blocks on.
`PctTheme`directive`[pctTheme]`	Theme as a template binding: `[pctTheme]="'dark'"` writes `data-theme="dark"` on the host — the attribute the generated skin keys its theme blocks on — and `null` removes it, so the system preference speaks again (`req-token-system`).

<section pctTheme="dark">
  <p>A dark island: every token below it flips.</p>
</section>

Examples

Every state, running

Each example is the component itself, not a screenshot. Open the code under any of them.

An island that switches

The directive writes one attribute; the tokens under it do the rest. Bind it to a signal and a whole region of the page changes theme without touching the document.

This island is dark.

API

What it reads, and what it writes back

Read from the source at build time — the types, the defaults and the lines of documentation are the library's own.

Theme as a template binding: [pctTheme]="'dark'" writes data-theme="dark" on the host — the attribute the generated skin keys its theme blocks on — and null removes it, so the system preference speaks again (req-token-system).

Inputs

Name	Type	What it does
`pctTheme`required	`PctThemeName \| null`	The theme to pin on this subtree, or `null` to follow the page.

Outputs

None of its own. The native events — (click), (focus), the form's submit — are the platform's, and two-way models above carry the rest.

What it writes on the element

The hooks a stylesheet or a test can hold. Stable by contract — the parts inventory gate fails the build when one disappears.

Attribute	Bound to	Note
`data-theme`	`pctTheme()`

Styling

Parts to select, tokens to override

Two ways in, both stable. No class names to depend on.

Parts

In a test, PctThemeHarness from @pacit/components/testing reads a part by the name below and a state by its attribute — the harness gate holds the names to the package.

No parts of its own — the element you write is the whole of it.

Tokens

Every value the component reads, with the light and the dark default. Override a token at any scope and it cascades like any custom property.

No tokens of its own — it paints from the semantic tier.

Accessibility

Measured, not assumed

Pattern: none — the directive writes one data-* attribute and touches nothing the accessibility tree carries. Named in the class JSDoc.

Evidence

What the repository holds for this component

Read at build time from the tracked snapshots, not typed here.

—mutation scoreno mutants to kill — the policy says why

4 × 3e2e cases × enginesplus the shared audits: axe, forced colors, preferences, size, hydration

0colour pairs measuredlight and dark, at every token build

0visual baselinesChromium, the sandbox's own pictures

4elements in the preview0 listeners · 1 render to settle · 1811 µs in jsdom, held exactly but for the clock

Why it is built this way

Sugar over the cascade (0059): [pctTheme]="'dark'" writes data-theme="dark" — the attribute the generated skin keys its theme blocks on — and null removes it, so the system preference speaks again. The mechanism stays the cascade itself; the sandbox measures a hand-written panel and a directive panel reading the same computed surface.

Known limitations

The app root keeps writing data-theme by hand — a bootstrap component has no template around it to bind an input on. One writer the directive cannot replace (0059).
Two theme names, no registry of skins. 'light' | 'dark' mirrors the blocks the skin actually ships; a third theme is a token-build feature first, and the union widens the day the build emits it.
No 'system' value. Following the system is the absence of the attribute, so it is spelled null — a 'system' string would be a third state pretending the attribute can express it.

pacit

Usage

Every state, running

An island that switches

What it reads, and what it writes back

Inputs

Outputs

What it writes on the element

Parts to select, tokens to override

Parts

Tokens

Measured, not assumed

Keyboard

What is measured, and what is not yet

What the repository holds for this component

Why it is built this way

Known limitations