---
name: kb-design-standard
description: Apply the verified KB Signaling Design System V1 to an explicitly requested UI change. Use the accepted WSDMM configuration-wizard baseline, reusable theme/CSS/Sass layers, native controls and documented component exceptions. Preserve application behavior and scope; do not apply the older Tempest control-ui-central palette or composition rules automatically.
---

# KB Signaling Design Standard V1

## Start with the actual project

Read the consuming repository's instructions and the user's scope before editing. Locate the KB standard checkout and read its current `scss/_tokens.scss`, relevant component mixins and usage document. In this checkout those are [tokens](../../scss/_tokens.scss), [adoption guide](../../docs/adoption.md) and [current integrated example](../../examples/components/css.html). Relative links assume this skill stays in the KB checkout. If installed elsewhere, resolve the same files from an accessible KB checkout; do not assume a workspace-specific absolute path.

Inspect the real consuming components, imports, utilities, variants and local overrides first. Record the existing behavior and state ownership. Use this standard for the requested scope; do not migrate an application simply because this skill is available. Preserve business logic, submissions, validation, routing and state. Teams may implement equivalent framework components; no React/FastAPI/Tailwind dependency or page composition is mandated.

User instructions take precedence. Resolve design uncertainty from the accepted implementation and current component documents, then actual WSDMM wizard evidence. The company guide and older control-ui-central skill are supporting references with explicit conflicts, not replacement implementations. Earlier generated previews, the original landing gallery and historical contrast proposals are not current authority. If a required source is missing, name it and continue with accessible evidence without inventing values.

## Six priorities and verified rules

1. **Fonts:** Noto Sans; actual loaded glyphs matter. Load optional `fonts.css` with `assets/fonts/noto-sans/` and the OFL notice, or use approved equivalent hosting. Normal weights 300–900 are supplied; do not synthesize an unavailable italic and call it verified. Preserve the established platform fallback chain. Use named responsive typography roles, not the company image's presentation scale for every UI. Values 16/24 weight 400; labels 14/20 weight 500; descriptions 12/16 mobile, 14/20 at 640px. See [typography](../../docs/typography-baseline.md).
2. **Fields:** native input/select/textarea, associated labels and explicit help/error linkage. Primary radius 14px, modal 10px; padding 12px block / 16px inline; one 1px contour; input/select 50px, rows 3 textarea 98px in verified examples. Source resting border is gray-300 light, white/20 dark. Hover retains it. Field focus uses `field-control-focus-border/ring`, with 50% primary and 20% modal halos; primary select keeps resting contour. Do not reuse the stronger legacy button-focus tokens or reintroduce dark-blue double borders. Current readable placeholders, fill and error roles are intentional differences. [Field rules](../../docs/fields-usage.md).
3. **Radius:** use component roles; do not flatten to one universal radius. Main card 16px mobile / 24px above 640; panels 14px; dense dialog 16px; glass 14px mobile / 16px above 640; actions have documented responsive variants.
4. **Colors:** match the accepted wizard page gradient and light/dark surface families. Light cards white; dark main card white/10 with blur 40. Company colors primarily support actions/chips/badges/accents. Avoid broad palette changes. Dark secondary/toolbar actions use white/10, not black fills; hover white/15 is the documented contrast refinement. Primary uses the existing #004a8f→#005a9c gradient with dark alpha stops. Source-specific scrim layers matter: do not replace translucent dialogs with a sampled solid hex. [Action rules](../../docs/actions-usage.md), [surface rules](../../docs/surfaces-usage.md).
5. **Borders/elevation:** keep role-specific contours: secondary action dark white/30, toolbar/add white/20; primary source blue/30. Device choices 2px, template choices 1px, with distinct hover/selected rings. Static cards are flat and do not lift on hover. Routine buttons are flat; small primary elevation is opt-in. Pressed feedback and keyboard focus remain independent. Use the source-specific dense/glass shadows and separators. Source subtle borders/halos are not certified as 3:1 contours; historical stronger-border evidence is superseded. Check the actual consumer backdrop.
6. **Icons:** Lucide, currentColor, no fill, stroke 2, round caps/joins. Routine 16px; Apply/add 20px; no arbitrary resizing. Icons in buttons are optional by use case. Text-only controls are supported. Decorative SVGs: aria-hidden=true/focusable=false. Icon-only controls need accessible names; SVG size is separate from the shared 40px target. Keep the Lucide license. [Icon rules](../../docs/icons-usage.md).

The token maps and component rules win over this abbreviated numeric summary if implementation changes after this revision. Read [source conflicts](references/conflicts.md) before interpreting the old skill.

## Reuse without global leakage

CSS: load `theme.css`, then optional `fields.css`, `actions.css`, `surfaces.css`. Load optional `fonts.css` separately with its assets/license. Root `.dark` selects the default dark theme. Theme output supplies variables; it is not a page reset or a runtime preference manager. The application owns preference/persistence.

Sass:

```scss
@use './path/to/kb/scss' as kb;
@include kb.theme($selector: '.application', $dark-selector: '.application.dark');
.application {
  @include kb.fields();
  @include kb.actions();
  @include kb.surfaces();
}
```

Import alone emits no CSS. `kb.type(value)` and other verified roles apply typography. Use bounded theme overrides when necessary; document the reason and check both themes. Do not hand-edit generated CSS, duplicate the whole palette into local utilities, or load both scoped and global bundles into the same component scope. See the [scoped consumer](../../examples/components/consumer.scss).

## Preserve semantics and behavior

Use native disabled and readonly where supported; readonly values remain focusable/submittable, disabled values do not. Native select has no readonly state. Invalid fields need text plus aria-invalid/aria-describedby, not color alone. Do not mark pristine required fields invalid automatically. A select wrapper may use the existing Lucide caret; retain native selection and forced-color fallback.

Passive badges are not buttons. Selectable chips own aria-pressed. Buttons need correct type; links need actual destinations. Busy actions prevent repeat activation and announce results. Never add icons merely because an action is primary.

Dialogs use showModal(), a visible accessible name, initial focus, Tab containment, Escape/close, focus return, and scroll restoration. Only body content scrolls. Native markup alone does not implement all lifecycle requirements. The demo resets disposable local data; production dirty-data handling must follow the app's existing policy. Do not copy demo save/reset handlers into business workflows.

## Verify and report

Follow the [adoption checklist](references/verification.md). Run only relevant checks for the change, plus required project checks. Verify real rendered styles in both themes and supported widths after transitions settle. Check default/hover/focus/invalid/disabled/readonly where applicable, dimensions/padding/radius, actual font loading, colors/borders, icons, keyboard and preserved behavior. Compare rendered alpha layers, not only computed token strings.

For shared source edits regenerate affected outputs with `npm run build:theme`, `build:fields`, `build:actions`, `build:surfaces`, `build:examples`; use their corresponding check scripts and `test:theme`. Keep proof and limitations precise: Chromium evidence is not cross-browser/accessibility certification. Recheck consumer backdrops and supported browsers. Don't claim obsolete contour contrast measurements for the restored source borders.

Report changed files, intentional differences, verification and remaining gaps. Update ROADMAP.md when working on the KB initiative, including its visual progress strip. Keep application edits within the user's authorized scope; no push, merge, migration or publication is implied by skill usage. Do not add an approval gate for ordinary authorized local work.

## Public documentation site integration

When working on this repository's public pages, preserve the shared frame described in [maintenance](../../docs/shared-frame-maintenance.md). Edit `site/navigation.json` and `site/header.html`, then generate with `npm run build:site`; do not create a replacement header, sidebar, theme key or menu handler for a detail/presentation page. Public pages use the same frame; page-local navigation stays in their content. Check `npm run check:site` and `npm run check:links` plus relevant rendered interactions. Standalone CSS/Sass consumer fixtures intentionally remain isolated; this site-frame rule does not mandate a navigation layout in consuming applications.