# Building with Alpha

Read this when creating new UI rather than replacing an existing implementation.
If Alpha is not integrated yet, read `setup.md` first. Then use `llms.txt` to
load only the foundation and surface documents the work needs.

Alpha supplies components, modules, icons and visual foundations. It does not
decide the application's routes, data flow, page structure or layout. Keep that
boundary visible while planning the UI: Alpha owns the contract inside a
published surface; the application owns how those surfaces are arranged and
what happens around them.

## Start with the job, not a component name

Before choosing a surface, state what the reader needs to do or understand:

- the semantic role and expected element;
- the content and accessible name;
- the available, disabled, pending, empty, error and success states that apply;
- who owns the state and whether it is controlled;
- the event the application needs and the value it must receive;
- focus, keyboard and dismissal behaviour;
- the surrounding layout and what changes at narrow widths.

Search `llms.txt` for surfaces that provide that capability. Read each
candidate's "When to use", "When not to use", props, states and guidelines
before selecting it. A familiar name is not evidence that the component does
the required job. Where a generated document and the emitted declaration ever
disagree, the `.d.ts` is the contract.

## Choose the ownership boundary

Use the smallest boundary that expresses the design without hiding behaviour:

1. **Use a published Alpha component** when its semantics, state and events
   match the requirement.
2. **Use a published Alpha module** only when the fixed arrangement itself is
   the requirement. Do not choose a module merely to save a few lines of
   composition.
3. **Compose Alpha surfaces in application markup** when the arrangement is
   specific to the feature. Forms, toolbars and page sections usually belong
   here.
4. **Use semantic HTML or an application-owned component** when `llms.txt`
   contains no matching surface. Do not construct an imitation from unrelated
   Alpha components, import an internal path or invent props that sound likely.

An application-owned component is useful when several call sites share feature
behaviour or layout. Keep its API in the language of the application and use
Alpha inside it where the capabilities match; do not expose Alpha's entire prop
surface by default.

## Build the composition

1. Import components from `@growth-protocol-ai/alpha` and icons from
   `@growth-protocol-ai/alpha/icons`. Import no path below `dist/`.
2. Start with the documented basic usage. Add a prop because the requirement
   calls for it, not to make every default explicit.
3. Put content in the documented place. A label may be children, a `label`
   prop, or external markup associated with a void element; these shapes are not
   interchangeable.
4. Decide state ownership deliberately. Do not pass a controlled prop without
   updating it from the corresponding event, and do not add local state when a
   form or feature controller already owns the value.
5. Match handler arguments exactly. A DOM event, a selected value and a
   no-argument action are different contracts even when the handlers share a
   familiar name.
6. Treat pending and disabled as behaviour, not decoration. Prevent duplicate
   actions, preserve the accessible state and keep the label meaningful while
   work is in progress.
7. Use one static icon import per glyph. Pass an icon element to an icon slot,
   let the surrounding component size and colour it, and label the control
   rather than the decorative glyph.

## Keep layout in the application

Alpha has no layout or typography primitives and no spacing or breakpoint
scale. Use semantic elements and the application's stylesheet for grids,
stacks, page widths, responsive changes and running text. Do not search for an
Alpha `Box`, `Stack`, `Grid` or `Typography`, and do not turn a component into a
layout primitive by pushing appearance rules through `className`.

Use this styling order:

1. Override a documented token when the product's visual foundation changes.
2. Put layout-only rules such as width, flex placement and margin on a root
   `className`.
3. Use a documented `[data-slot="..."]` or `[data-module="..."]` selector for a
   contextual rule that must reach a published part. Read `slots.md` before
   styling an overlay because portalled content is not a DOM descendant of its
   trigger.

Never target Alpha's generated class names, recreate a variant's geometry, or
pass an `sx` prop or style object. If the desired appearance requires changing
the component's private structure, the requested design is outside the
published contract and needs a design decision rather than a CSS workaround.

## Accessibility is part of the selection

- Prefer the native element whose meaning matches the action or content.
- Give every control an accessible name. Associate fields with visible labels,
  and use `aria-label` for a control that intentionally contains only an icon.
- Preserve the keyboard and focus behaviour documented for compound and
  overlay surfaces. Do not put an interactive element inside another one.
- Connect help, validation and status text through the semantics the feature
  needs; proximity and colour alone do not create a relationship.
- Exercise focus movement, dismissal, keyboard activation and announced state
  directly. A typecheck cannot verify them.

## Track work that spans files

Use the consuming repository's existing issue or implementation-plan format.
If it has none and the work will span sessions, keep a short `alpha-ui-plan.md`
with one row per feature area: required capability, chosen Alpha surface or
`none`, state owner, status and validation. Update it with each batch so
remaining states and accessibility checks are not held only in conversation
memory.

The plan is discovery state, not permission to broaden the feature. Mark a
surface complete only after its behaviour is exercised, and record why an
application-owned implementation was chosen when Alpha has no match.

## Validate the finished UI

Run the application's own typecheck, lint and tests, then use its visual harness
where one exists. Check every relevant state in both modes and at the layout's
responsive boundaries. Exercise events, controlled state, focus, keyboard
behaviour and overlays rather than treating a clean render as proof.

Finally, search for internal Alpha paths, generated class selectors, unsupported
props and duplicated stylesheet imports. The UI is complete when the required
behaviour is present through public contracts—not merely when every visible
piece carries an Alpha import.