# Components and markup contracts

These are modern primitives in `sds.css` and `sds.js`. Styling is not a complete widget. Application state, server processing and advanced keyboard behavior require implementation.

## Actions

```html
<a class="sds-btn sds-btn--primary" href="/work/">Explore work</a>
<button class="sds-btn" type="button">Copy code</button>
<button class="sds-btn sds-btn--accent" type="submit">Send enquiry</button>
```

Use links with destinations for navigation and buttons for operations. Base actions have a 48px minimum height (46px at the narrow CSS breakpoint). Preserve focus indication; show pending text, true disabled state and recoverable errors when relevant. Copying, submission and network status are application code. Never nest controls inside linked cards.

The default (secondary) button and `.sds-field` use `--sds-border-strong`, which has at least 3:1 contrast against paper and surface in both schemes.

### Sizes

```html
<button class="sds-btn sds-btn--sm" type="button">Filter</button>
<button class="sds-btn sds-btn--lg sds-btn--primary" type="submit">Join the walk</button>
<button class="sds-btn sds-btn--icon" type="button" aria-label="Close">
  <svg aria-hidden="true" focusable="false" viewBox="0 0 20 20" width="20" height="20">...</svg>
</button>
```

`.sds-btn--sm` is 40px tall and `.sds-btn--lg` is 56px tall at every width. `.sds-btn--icon` makes a square button with no gap (48px, or 40px or 56px when combined with a size). An icon-only button needs an accessible name, such as `aria-label`, and its icon should be hidden from assistive technology.

### Danger

```html
<button class="sds-btn sds-btn--danger" type="button">Delete draft</button>
```

Use `.sds-btn--danger` only for destructive or irreversible operations. Its label must say what will happen; color does not carry the warning on its own. Ask for confirmation in application code where the action cannot be undone.

### Busy and disabled states

```html
<button class="sds-btn sds-btn--primary" type="submit" aria-busy="true">Sending</button>
<a class="sds-btn" aria-disabled="true">Next chapter</a>
```

`aria-busy="true"` adds a small spinner after the label. The spinner does not rotate under reduced motion or `data-sds-motion="still"`. Change the visible text as well (for example "Sending") and remove the attribute when the operation ends. On an icon button the icon is hidden while busy.

`aria-disabled="true"` looks the same as `:disabled` and blocks pointer clicks, but it does not stop keyboard activation. Your script must ignore activation while it is set. For a link that should not go anywhere, remove its `href`. Prefer the native `disabled` attribute on buttons unless the control must stay focusable so people can find it.

## Surfaces

```html
<article class="sds-card sds-stack" aria-labelledby="guide-title">
  <span class="sds-badge">Guide · 8 min</span>
  <h3 id="guide-title">Choose a composition</h3>
  <p>Match reading order to the task and content you have.</p>
  <a href="/guides/layout/">Read the composition guide</a>
</article>
```

`.sds-card` provides a border, ground, padding and radius. It does not make its whole surface interactive or supply selection state. Use a list for peer items and article for independent content. Badge text is supplementary, not a replacement for a state label. `.sds-muted`, `.sds-label` and `.sds-rule` add visual hierarchy without changing semantics.

## Status badges

```html
<span class="sds-badge sds-badge--success">Published</span>
<span class="sds-badge sds-badge--warning">Draft</span>
<span class="sds-badge sds-badge--danger">Overdue</span>
<span class="sds-badge sds-badge--info">New</span>
```

The four modifiers color the badge text with the matching `-text` token and the border with the matching fill. The word inside the badge must state the status; color only supports it.

## Alerts

```html
<div class="sds-alert sds-alert--warning">
  <p><strong>Route closed.</strong> The riverside path is flooded until Friday.</p>
</div>
```

`.sds-alert` is a bordered callout with a 4px border on the inline-start side. Modifiers `--success`, `--warning`, `--danger` and `--info` change that border color. Text stays in the ink color. Start the message with a clear word such as "Error" or "Saved" so the meaning does not depend on color.

Content that is present when the page loads needs no ARIA role. Add `role="status"` (polite) or `role="alert"` (urgent) only when the alert content changes dynamically after load, for example after a submission result arrives. Put the role on a container that already exists in the page, then change its text. Do not use `role="alert"` for routine messages.

## Reading text

```html
<div class="sds-prose">
  <p>Paragraphs, lists and <a href="/guide/">links</a> get comfortable spacing.</p>
  <p>Inline <code>code</code> uses the mono font.</p>
</div>
```

Paragraphs no longer have a global width limit. `.sds-prose` limits its width to `--sds-measure` (65ch), adds space between paragraphs and lists, underlines links and styles inline code. Use `.sds-measure` alone when you only need the width limit.

## Fields

```html
<form class="sds-stack" action="/enquiries" method="post">
  <div>
    <label for="email">Email address</label>
    <input class="sds-field" id="email" name="email" type="email"
      autocomplete="email" required aria-describedby="email-help">
    <p id="email-help">We use this to reply to your enquiry.</p>
  </div>
  <button class="sds-btn sds-btn--primary" type="submit">Send enquiry</button>
</form>
```

`/enquiries` is illustrative: implement the endpoint before publishing. `.sds-field` styles native fields; it does not validate, submit or save. Associate errors with `aria-describedby`; set `aria-invalid` after validation fails and preserve entered values. Announce confirmed asynchronous results with a polite live status. Field borders use `--sds-border-strong` for at least 3:1 non-text contrast against paper and surface. If you change field or page colors, check the boundary again.

## Navigation disclosure

`[data-sds-menu]` on a button uses `aria-controls` to find an element, toggles its `hidden` attribute and updates `aria-expanded`. Supply an explicit initial state. This simple disclosure does not implement modal focus trapping, Escape behavior or ARIA menu arrow keys. Ordinary navigation should use ordinary links. For no-JavaScript access, expose links initially and collapse them only after successful wiring.

## Glyph text and advanced patterns

`data-sds-float` opts text into slow gravity drift. The root preset `data-sds-text="gravity"` includes ordinary copy, navigation and CTA labels. Source words and hit targets stay in place; decorative grapheme copies return on leave or pointer release. `initGravityText` supplies stop/destroy lifecycle controls. The older `data-sds-glyphs` symbol substitution remains separate outside gravity mode. Fields, code, editing and essential status messages are excluded. Test real scripts and selection. Read [motion](motion.md) and [the showcase contract](expressive-motion.md).

`initSquareActions` gives `.sds-btn`, `.sds-scene-button`, retained `.btn` and custom `[data-sds-action]` square geometry and a theme-colored light after pointer/keyboard entry. Lighting persists only for the page visit and does not imply a pressed or successful state. Native focus remains visible.

Modern tabs, dialogs, comboboxes, sortable tables, uploads, authentication and chart behavior are not complete shipped widgets. Native `details` can serve a simple disclosure and native tables can represent data. Implement and document advanced keyboard models, focus, state and failure behavior explicitly. Legacy `sy-*` widgets have different contracts; they are not automatic `sds-*` aliases.
