Components

Initial reusable components

Button, Link, Text Input and Form Field are implemented reusable React components in the Release 1.0 Approval Candidate. They consume the accepted foundations independently of this documentation shell or a particular corporate website. Their existing component-level working treatments are internally accepted for this release scope. Specialist and application-specific validation and final company approval remain pending.

Only these four components are included. No icon-only action, loading state, destructive variant, custom validation engine or production form workflow is provided. Documentation specimens below use the actual components and generic illustrative text.

Button

Use a Button for an action and a Link for navigation. Anatomy: native button, wrapping text label, control boundary and an external keyboard focus ring. Primary actions use accessible interactive orange, not decorative brand orange. Secondary actions use charcoal on white with a meaningful control border.

import { Button } from "@/components/ui/button";

<Button onClick={handleAction}>Example action</Button>
<Button variant="secondary" type="submit">Submit example</Button>
<Button disabled>Unavailable action</Button>

Link

Use a real destination, not an action disguised as navigation. Anatomy: native anchor, descriptive destination text and visible underline/focus. Inline text links wrap with their paragraph. Standalone links retain the same colour and underline, using UI metrics and a minimum 48px target.

import { Link } from "@/components/ui/link";

<Link href="/docs/foundations/colours">Colour reference</Link>
<Link context="standalone" href="#details">Read details</Link>

The base anchor has no Next.js dependency. A future application-specific router adapter can compose it through the router's supported anchor interface, forwarding href, attributes and ref once. An adapter needs its own navigation tests; none is introduced here.

Text Input

Use Text Input for a standard single-line text value. Anatomy: native text input, readable value, meaningful border and external focus ring. Always provide an associated visible label, directly or through Form Field. A placeholder is supplementary, never the label.

import { TextInput } from "@/components/ui/text-input";

<label htmlFor="example">Example text</label>
<TextInput id="example" name="example" defaultValue="Illustrative value" />

Form Field

Use Form Field when a single text input needs a visible label and optional helper/error descriptions. Anatomy and reading order: label, exactly one Text Input, helper, error. This wrapper adds associations, not business validation, submission handling or form state.

import { FormField } from "@/components/ui/form-field";

<p id="caller-help">Illustrative instructions.</p>
<FormField id="example-field" name="example"
  label="Example text" required requiredIndicator="Required"
  aria-describedby="caller-help"
  helperText="Generic helper description."
  errorText={hasError ? "Error: review this example value." : undefined}
  defaultValue="Illustrative value" />

Foundation and token mapping

Decorative --border-default is used only on documentation specimen containers, never as the input or secondary-action boundary. The documentation sidebar's solid-orange selected treatment is not a reusable navigation rule.

Accessibility, reflow and bilingual use

Native semantics preserve keyboard behaviour: Space/Enter activate buttons; Enter follows anchors; text inputs support editing and selection. Disabled buttons/inputs are unavailable. Read-only input remains focusable. Visible labels, error words and descriptions provide meaning beyond colour. Focus uses a 2px ring and 2px local-surface gap, with a system Highlight fallback in forced colours.

Wrapping labels and feedback increase height. Inputs stay within available inline width and scroll long single-line values internally. Standalone controls retain 48px minimum targets; inline prose links follow text flow. Leave space for external focus rings and at least 8px between adjacent targets. Do not place groups inside clipping containers.

Set lang="ar" and dir="rtl" for approved Arabic content; existing language aliases select IBM Plex Sans Arabic metrics. Keep English sections explicitly lang="en" and direction appropriate. Use logical CSS placement and isolate known-direction identifiers with bdi in surrounding text. Input direction belongs to the value's meaning, not an automatic script guess. No Arabic specimen copy or translation is supplied here.

Technical direction and CSS checks cannot establish Arabic-language comfort. Native-reader review, assistive-technology checks, actual browser zoom, native forced-colours and real devices remain pending. No comprehensive WCAG conformance is claimed.

Developer integration

Use explicit leaf imports from components/ui. These four files have no filesystem, PDF, documentation-shell, routing or icon dependency. Load the existing fonts.css, tokens.css and typography.css once in the consuming application's stylesheet entry, in that order; use the existing tokens rather than copying a second theme. Global token and language styles are prerequisites; documentation globals are not.

The leaves have no client directive or internal state. React 19 native ref props pass through to their native elements, including Form Field's nested input. Server-render static instances; place interactive callers with handlers, controlled state or refs behind the consuming application's Client Component boundary. Do not pass event handlers from a Server Component. This page's small example module owns only specimen state.

Caller className and style can override presentation and therefore need consumer validation. Do not use them to bypass foundation rules. No broad export package, router adapter, form schema, context provider or extra dependency is introduced.

Validation, sources and approval

These four components and their existing working treatments are internally accepted within the Release 1.0 Approval Candidate scope. Automated checks cover the documented native contracts and representative browser behaviour; their results and exact limitations are recorded in docs/stage-03.2-initial-components.md. Specialist accessibility and Arabic review, real-device and application-specific checks and final company approval remain pending. This is not a universally certified production library.

Internally accepted treatments: secondary hover/active neutral fills; matching primary fill/boundary; underlined action-colour links with unchanged visited palette and standalone UI treatment; read-only secondary surface; caller-owned field IDs and optional required wording. This resolves the initial D-01/D-02 review status for these four components without changing global tokens or source specifications. Future variants and other inventory components remain separate, unimplemented scope.

• Colours: v1.0 pp4,11, actions, disabled and semantic roles.
• Typography: v1.0 pp4,5, field/UI metrics and language handling.
• Spacing and Layout: v1.0 pp2,3, comfortable controls, descriptions and targets. Compact p3 interpretation remains unchanged.
• Geometry: v1.0 pp3,4,9,12, control radius, meaningful/error boundaries, stable geometry and focus.
• Iconography: v1.0 pp3,9,15, semantics and target context. No glyph abstraction or icon-only control is added.

Source: the internally accepted working foundation PDFs in reference/brand-guidelines/, existing central styles, and the Stage 03.1 component inventory. Original sources and all nine foundations remain unchanged. Specialist validation and final company approval remain pending.