Core UI — Implementation rules

Part of the design proposal. See mockups for visual examples and the component catalogue for each study's purpose and candidates.

Overview

These are proposed design rules extracted from the current exploratory browser prototype. They describe the intended shared vocabulary, its current candidate values, and unresolved boundaries. They are authoritative within this draft design set, not an accepted production specification. Mockup-only values are identified separately.

The prototype uses React, Vite, Bun, Radix Themes 3.3.0, and Radix Primitives through radix-ui 1.8.1. Those technologies and package boundaries remain exploratory under draft RFC-0002. Platform-independent rules concern perception, semantics, state, and navigation; CSS names below are the current web expression of those rules. Current implementation facts and installed API coverage belong in the prototype reference and package reference.

Copyright and licence

Copyright © 2026 White Eclipse.

This document is released under the MIT License. See the project's root LICENCE file for the complete licence text.

Requirement terminology

Uppercase requirement keywords follow IETF BCP 14, as defined by RFC 2119 and clarified by RFC 8174. MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL carry those meanings only when written entirely in uppercase. They specify the proposed design, not owner approval.

Building blocks

The area-based catalogue lists all 73 current studies, their two comparison candidates, semantic responsibilities, and state contracts. Each has Playground and Comparison views. A candidate may represent density, placement, orientation, or state rather than an alternative skin. Nonvisual utilities retain their real composition responsibilities.

Consumers compose typography, layout, content, and controls rather than reproducing a page screenshot as a single image. Shared rules MUST apply consistently to equivalent states. Component-specific contracts supplement the common rules below. Demonstration controls and sample content are not a new application API; exact production props, package exports, and dependency adoption remain technical decisions.

Common state contract

Visual rules

Colour and theme

Warm off-white #f6f4ef and charcoal #211f26 anchor the proposal. Light and dark appearances use the same semantic roles with different values. Consumers SHOULD use roles rather than a light-theme hex value in every control. The supplied company logo MUST match the active surface appearance, including after an in-application theme change.

The extracted opaque scale is:

The roles describe proposed use, not a guarantee that every foreground/background pairing passes contrast review. The corresponding twelve translucent values, extracted from the same theme, are:

The current aliases map page background to gray-1; solid/translucent panels and general surfaces to gray-2; indicators and tracks to gray-9; contrast foreground to off-white in light appearance and charcoal in dark appearance. The neutral theme uses gray accent and sand gray-family configuration. Error/destructive examples currently use upstream red; final feedback colour tokens remain a material open question. Coloured project artwork is not an interface status palette.

Theme values MUST remain consistent across nested surfaces and overlays rendered outside their original container. The prototype applies the same overrides at inherited Radix theme boundaries; opening a dialog or menu does not reset appearance to light. Theme configuration controls in the catalogue are experiments, not permission to vary brand roles arbitrarily.

Typography and hierarchy

Typography MUST use the following roles consistently:

The web stylesheet MUST load these families from Google Fonts using its CSS v2 API, with display=swap and fallback stacks so content remains readable while fonts load or when the service is unavailable. The current request covers weights 300–700 for all three families and true italics for Inter and JetBrains Mono. Outfit is requested upright for the brand and display headings. The shared stylesheet owns the request; individual components MUST NOT independently reload the fonts. These roles also apply to nested theme and portal surfaces. External font loading requires access to fonts.googleapis.com and fonts.gstatic.com; blocked/offline loading falls back and may alter wrapping. The semantic h1/h2 role determines Outfit usage independently of a component's visual size. Emphasis and inline quotation retain their semantics while inheriting Inter rather than upstream serif defaults.

At the prototype's default 100% scaling, the text scale is:

The default body is 16px with 1.5 line height. Typography components supply their own semantic heading/emphasis adjustments; the body table is not a heading line-height contract. Font weights in the underlying scale are light 300, regular 400, medium 500, and bold 700. Candidate-specific 600-weight labels remain local.

Headings MUST preserve logical document hierarchy independently of visual size. Short uppercase annotations may use wide tracking; long prose, field labels, and navigation labels SHOULD remain easy to scan without artificial spacing. The landing's editorial headings are examples, not replacements for every component heading size.

Spacing, sizing, and surfaces

The spacing scale at 100% is 4, 8, 12, 16, 24, 32, 40, 48, and 64px (space-1 through space-9). Related controls use a smaller gap than separate content sections. Layout MUST preserve readable order when columns stack or labels wrap.

Shared surfaces are flat. The default radius is zero; this does not replace a radio's circular selection symbol or remove a switch thumb's distinct shape. Decorative elevation shadows are disabled. Use a single-pixel border/divider or a subtle inset stroke where a surface needs definition. The current button inset stroke uses translucent boundary role gray-a6; primitives generally use gray-7 for control boundaries and gray-2 for their surface. Candidate variants may deliberately strengthen these boundaries.

Control size selection stays component-specific: primary/icon buttons expose sizes 1–4, while the early checkbox/radio-group/switch studies expose 1–3. The draft does not invent a universal control-height table or touch-target guarantee from those indexes. Production size mapping and minimum target policy need review before acceptance.

Corner-frame controls and motion

The primary action has a transparent resting surface and eight 1px strokes, two per corner, initially 8px long in each direction. Hover or visible keyboard focus extends opposing strokes until they form a continuous border, with no layout shift. Retraction uses the same 180ms ease-out transition. The plain candidate has no extra symbol; the marker candidate adds a 6px square. Neither candidate is formally selected by this extraction.

The corner icon-button treatment uses the same frame. Toggle candidates retain their selected state after hover: the fill treatment inverts foreground/background, while the marker treatment fills its square and completes its frame. Checkbox, radio, and switch corner candidates use initial 4px strokes. Their check/dash, circular dot, or moving thumb MUST remain distinguishable from frame decoration. Disabled and loading action frames do not animate; disabled foreground currently uses gray-8.

Motion MUST support comprehension without delaying activation. Reduced-motion preferences suppress visible transitions and decorative animation. The web prototype sets animation/transition durations to 0.01ms with one animation iteration and disables smooth scrolling; the near-zero duration preserves completion events. No global animation duration is defined for every overlay. Final per-component overlay timings remain part of variant review.

Icons, logo, and imagery

Foldable items use a plus when collapsed and a minus when expanded. Four separated 3px corner segments frame the symbol with 1px strokes, inset 1px in a 16 × 16px indicator. The shared stylesheet draws the marker with currentColor background layers; the linked SVG studies show the earlier static treatment. Hover and visible keyboard focus extend opposing strokes to 50% over 180ms ease-out, completing the square as on the buttons; exit retracts them. Disabled triggers retain the resting frame. Reduced-motion preferences suppress visible animation. Plus/minus state still changes immediately without rotation. Native summaries and opted-in Accordion/Collapsible triggers share the markers. Hover/focus inversion preserves the symbol; labels, disabled states, expansion semantics, and keyboard behaviour remain native or Radix responsibilities.

Font Awesome is the proposed website icon vocabulary explored in the landing mockup. Use icons consistently, retain visible labels where useful, and provide an accessible name on any icon-only action. Decorative icons MUST NOT duplicate their adjacent label in the accessibility tree. Library-supplied semantic indicators may remain where replacing them would harm meaning or interaction; the existing Radix utility icon studies remain explicit comparison material, not a completed icon migration.

The company logo is a supplied image asset, separate from Font Awesome. Preserve its aspect ratio and colours; select the dark mark for a light surface and the pale mark for a dark surface. When adjacent text already names White Eclipse, the repeated image uses empty alternative text; a standalone linked logo needs an accessible destination/name. The sample's 64px logo box (48px on narrow layouts) is a composition measurement, not a universal logo minimum or clear-space standard.

The orbital and eclipse images are generated temporary artwork. They demonstrate how images can sit alongside shared components; they are not reusable control graphics, final portfolio models, or a new status colour system. The page and component mockups MUST remain rendered from components rather than replacing the interface with a generated screenshot.

Optional woven background

The background study translates the reference into White Eclipse colours without the ornamental side rails. It is optional for composed surfaces; plain page/panel backgrounds remain valid for dense reading, forms, and overlays. The landing and documentation samples both use the fixed woven texture and geometry from one shared sample stylesheet. The documentation sample restores this treatment behind its reading layout; it does not change the geometry or ink values below.

The drawing uses a square with side max(100vw, 100vh) aligned top-right, so its 135° centre line and radial centre coincide at every aspect ratio. It MUST NOT intercept pointer input, create focusable content, animate, or cause horizontal overflow. Fine lines and texture are decorative; meaningful text and component boundaries still require their own sufficient contrast. Forced-colour and full browser/assistive-technology behaviour remain unverified. An application may omit this treatment when it competes with content.

Landing-only composition measurements

These values describe the mockup, not mandatory Core UI page geometry:

The generic comparison frame uses two columns with 32px gaps/padding and stacks at 720px or below with 24px padding. Earlier checkbox/radio specimens stack at 640px or below. These catalogue presentation values are not application navigation breakpoints. The landing's section order, wording, available links, and generated illustrations remain illustrative.

Interaction and accessibility

The proposed web review target is WCAG 2.2 Level AA, subject to owner confirmation and the support scope in open questions. No conformance result is claimed. The W3C ARIA Authoring Practices Guide supplies informative pattern guidance; its keyboard interface guidance distinguishes Tab movement between controls from navigation inside composite widgets. Use native semantics where they fit the task.

• Focus and activation: Tab/Shift+Tab follow meaningful order. Buttons support their expected keyboard activation; links navigate on Enter. A visible 2px foreground focus outline with 3px offset remains separate from hover/selection. Overlay or decorative layers MUST NOT hide focus.
• Selection: Checkbox activation toggles checked state; the mixed checkbox example becomes checked on activation. Radio groups keep one selected value and expose it with a dot. Arrow navigation skips disabled choices. Switches communicate on/off with thumb position. Toggle actions expose pressed state and keep a stable action name.
• Composite navigation: Menus, tabs, toolbars, selects, and groups use the appropriate internal keyboard pattern rather than adding every item indiscriminately to the page Tab sequence. Implementations MUST document activation and dismissal behaviour per component; library defaults alone are not a verification result.
• Overlays: Dialogs expose a title and useful description, contain focus when modal, support cancellation, and restore focus appropriately. Escape/outside dismissal is applied according to the component's interaction pattern. Confirmation dialogs provide an understandable cancel route; tooltips/hover cards do not become the only place essential instructions are available.
• Fields and feedback: Visible labels identify inputs; descriptions and errors are associated with their control. Invalid input remains correctable. Read-only differs from disabled. Status text is exposed without moving focus unnecessarily. Toasts are supplementary feedback, not the sole record of a critical outcome.
• Themes and decoration: Portalled content inherits the active appearance. Colour alone does not convey selection or failure. Backgrounds and ornamental artwork have no interactive role. Contrast review includes the actual textured surface and every active/disabled/selected treatment where applicable.
• Adaptation: Long labels, 200% text resizing, narrow layouts, touch, and right-to-left reading need review. Direction-provider examples demonstrate a capability rather than a translated product. The landing's FR control is deliberately unavailable; EN is a displayed state, not an implemented language switch.

The proposed WCAG review includes text/non-text contrast, reflow, visible/unobscured focus, keyboard access, labels, error identification, status messages, and target size. Resolve actual exceptions and supported contexts during review rather than treating a muted border or a compact mockup as proof of compliance.

Verification

Use the README validation for the complete proposal and the component contracts to select observable checks. The mockups contain static evidence; the prototype reference records executed commands and manual observations.

For this documentation extraction, metadata, required section order, local links and heading anchors, referenced assets, sequential revision histories, all 73 study references, and opaque/translucent colour values were checked against the current sources. The existing catalogue coverage check passed again. A fresh full-page landing capture was visually inspected. At that extraction, application source was unchanged; application builds and unit/integration/accessibility suites were not rerun for that documentation-only change. Earlier build and interaction evidence remains identified separately.

For the 2026-10-20 typography/background update, type checks, both builds, and catalogue coverage passed. Source review checked shared font roles, both background consumers, and wireframe XML. Browser font loading, final wrapping, scrolling, contrast, and narrow-layout rendering remain unverified because local browser access was declined earlier in this session. Unit/integration tests were omitted for this exploratory update.

Extraction sources: shared theme, theme boundary, early control styles, catalogue styles, landing styles, and the per-component source links in Components. These identify the current exploratory implementation rather than an adopted technical specification.

Existing exploratory evidence includes representative dialog focus/Escape restoration, menu action feedback, select navigation past disabled choices, form validation, password visibility, sequential synthetic code entry, and toast triggering/dismissal. It does not establish production authentication, data submission, error recovery, or permission enforcement. Unit/integration and automated accessibility suites were omitted during exploratory implementation. Before promotion, complete the required design review and reassess production test coverage; do not equate export coverage with state coverage or acceptance.

For the 2026-10-20 disclosure-chevron update, type checks, both builds, and catalogue coverage passed (73 studies, two samples, 148 stories). Browser checks confirmed accordion and collapsible expansion, native directory expansion with the pointer retained on the focused row, and light/dark accordion rendering. Static checks confirmed the supplied SVG path/fill rule, local documentation link targets, metadata, notices, and sequential revision entries. Unit/integration tests were omitted for this exploratory change; mobile, reduced-motion, forced-colour, and assistive-technology behaviour were not exercised. Human design and RFC acceptance remain pending.

Revisions