# About

Source: https://teasim.com/about.md

## Why we exist

Most component libraries make two decisions on your behalf. They decide how
your site looks, by shipping a stylesheet. And they decide how your site is
built, by rendering your content for you. Both are borrowed decisions, and both
are expensive to undo two years later when you want something they did not
anticipate.

Teasim tries to make neither.

## How the split works

`@teasim/astro` renders markup and carries behaviour with it. It ships no
stylesheet at all; your own TeaCSS build generates exactly the classes your
markup used.

`@teasim/aster` arranges those elements into the page-level chrome a site
repeats — the shell, the header, the navigation, the table of contents. It owns
arrangement and never restates a surface.

`@teasim/astra` computes navigation, validates content, and serves the
machine-readable routes. It renders nothing.

No package knows what the others look like, and a project can take any of them
on its own.

## What we optimise for

**The markup you would have written.** An accordion is a `details` element. If
you inspect the DOM and find something you would not have written by hand, that
is a defect.

**Behaviour without JavaScript first.** The open state belongs to the browser.
A runtime binds on top when there is one, and the page works when there is not.

**Decisions that are written down.** Where something looks like removable
duplication and is not, the reason lives beside it, so the next reader does not
have to rediscover it by breaking something.

---

# Acceptable use policy

Source: https://teasim.com/acceptable-use-policies.md

## 1. Scope

This page would govern use of a hosted service. Teasim publishes packages rather
than running a service, so nothing here restricts anything today. It exists to
demonstrate the policy template.

## 2. The software

Use of the packages is governed by their MIT licence, which permits commercial
use, modification, distribution and private use, and which asks only that the
copyright notice travel with the code.

## 3. What a policy of this kind usually covers

A real acceptable use policy names the conduct a service will not host:
attempting to breach its security, interfering with other users, automated
access that degrades it for everyone, and distributing content the operator is
required to remove.

## 4. Reporting

A hosted service names a route for reporting abuse and commits to a response
window. See the [DMCA policy](/dmca-policy) for the takedown-specific version of
the same shape.

## 5. Enforcement

A real policy states what happens when it is breached, and in what order —
notice, suspension, termination — so the consequences are predictable rather than
discretionary.

---

# Approach

Source: https://teasim.com/approach.md

## Start from the markup

Design the DOM before the API. If the element you would have written by hand is
a `details`, the component is a `details`. Props exist to arrange markup, not to
hide it.

## Measure instead of reasoning

Where a question has a number attached, get the number. Whether a rebuild is
redundant is a hash comparison, not an argument. Whether a role belongs on an
element is a count of how many appear on a page. Whether a colour passes is a
pixel read back off a canvas with the whole ancestor stack composited onto it.

Reasoning is what you do when measurement is impossible, not when it is
inconvenient.

## Verify the thing that ships

A green build proves the code compiles. It proves nothing about what a browser
does with the output. After a component change, open the page.

The corollary is that verification has to be *hostile*: run the check against a
case whose answer you already know, and if it agrees, then trust it on the cases
you do not.

## Let the gate do the blocking

A check you read with your eyes is a report. If it is meant to block, the exit
code has to be the condition.

## Write down what you decided not to do

A decision that produces no diff leaves no trace. The next review will reach the
same question, spend the same time, and may answer it differently. Where it
matters, a test pins the current shape and names the reason in its title.

## Prefer the boring failure

Given two designs, prefer the one whose failure is loud. A class name assembled
from a template literal produces no CSS and no error — the markup looks correct
and the element is simply unstyled. A literal string that is wrong produces a
rule you can see in the stylesheet.

---

# Attributions

Source: https://teasim.com/attributions.md

## The element package takes none

`@teasim/astro` has no external runtime dependencies, and neither does
`@teasim/aster`, whose only peer is `@teasim/astro` itself. Where a browser
primitive exists it is used directly — `details` for disclosure, `dialog` for modals,
`popover` where it is supported. Where one does not, the behaviour lives in a
small shared runtime inside the package.

This is a constraint, not an accident, and it is checked: the dependency
boundary is that the element package takes nothing and the content package may,
so where a feature needs a dependency, that need decides which package it
belongs in.

## What the site uses

**Astro** builds the site and owns the content collections, the markdown
pipeline and the view transitions.

**TeaCSS** generates the stylesheet by scanning source for whole class tokens.
Every utility on this site is a class in the markup; nothing is written by hand
except a handful of gradients that a utility cannot express.

**Shiki**, through Astro's own markdown pipeline, highlights code at build time.
The components frame the result and never tokenize it themselves.

**IBM Plex Sans** and **IBM Plex Serif**, self-hosted at build time.

## Standards

The interface targets WCAG 2.2 AA. The criteria that shaped the most decisions
here were 1.4.10 Reflow, 1.4.11 Non-text Contrast, 1.4.12 Text Spacing, 2.4.1
Bypass Blocks, and 2.5.8 Target Size.

---

# Brand

Source: https://teasim.com/brand.md

## The frame

Every band on this site sits inside a rail on each edge. The rail is
`clamp(1rem, 18.75vw - 6rem, 3rem)` wide, so it grows with the viewport and
stops at 48 pixels, and it always draws the line at its inner edge. Above 1440
pixels a gutter opens between the rail and the content column and draws a
second line at its own inner edge — 1440 because that is the first width where
the gutter is wide enough for the two lines not to read as one thickened rule.

The content column is capped at 80rem. Everything else is margin. The gutter
absorbs whatever is left over, which is what keeps the two sides symmetric
rather than piling the slack against one edge.

## Corner nodes

Where two bands meet, a six-pixel square rotated 45 degrees marks the corner,
offset so its centre sits on the seam. That only holds because of one
invariant: every frame row draws the boundary as a border on its own bottom
edge, and the last row on the page draws none. A border moves the row's padding
box by the same pixel the node is offset against, so the node lands on the line
without knowing anything about the row on the other side. A line drawn by
anything else — an absolutely positioned hairline, a border on content nested
inside the row — misses by one pixel, every time. They are decoration, hidden
from assistive technology, and they are the one flourish the system allows
itself.

## Lines carry the structure

There are three kinds of line and they are not interchangeable:

- **Rails and seams** are full-strength `gray-500`, painted as real borders.
  They are structure, and they must survive forced colours — which a border
  does, and which the seam names explicitly anyway.
- **Hatching** is a 135-degree repeating gradient, one pixel of ink every five.
  It marks a major division between sections.
- **Wisps** are alpha tints at around 28%. They are ornament. They are allowed
  to disappear under forced colours, because a deliberate whisper repainted at
  full contrast is not the same design.

## Type

IBM Plex Serif sets every heading, at weights between 340 and 400 — light enough
that a large heading does not shout. IBM Plex Sans sets body text. The mono face
carries eyebrows, metadata and code, always uppercase with wide tracking when it
is a label.

## Motion

One transition, 150 milliseconds, ease-out, on colour and small translations.
The page frame scales fractionally when a sheet opens over it. Everything stops
under `prefers-reduced-motion`.

---

# Contributor agreement

Source: https://teasim.com/cla.md

## 1. Scope

The packages are MIT-licensed. Contributions are accepted under the same
licence, which for most projects of this size makes a separate signed agreement
unnecessary.

## 2. What you confirm by contributing

That you wrote the contribution or have the right to submit it, and that you are
willing for it to be published under the project's licence. Where an employer
owns your work, that permission has to come from them rather than from you.

## 3. What a contribution includes

Code, tests and documentation together. A change that alters behaviour without a
test that would fail on the old behaviour is incomplete, and a change that
alters a documented contract without updating the document is also incomplete.

## 4. Review

Contributions are reviewed adversarially: the reviewer's job is to try to refute
the change rather than to approve it. That is not a comment on the contributor —
it is the only way to catch decisions that no test can fail.

## 5. What is not accepted

Dependencies in the element package. It takes none by design, and a contribution
that adds one belongs in the content package or nowhere.

---

# Accordion

Source: https://teasim.com/components/accordion.md

## Installation

The open state is `<details>` and `<summary>`, so a row opens before any
JavaScript runs and keeps working if none ever does. A delegated runtime binds
on top to add what the element has no answer for — arrow-key roving focus,
`multiple`, `defaultValue`, and an `accordion:change` event. There is no client
directive to write; it binds itself and survives a view transition.

## Preview

      <h3>Does this need JavaScript?</h3>
      No. The disclosure is the browser's, and so is the exclusive-group behaviour when items share a `name`.

      <h3>Where do the styles come from?</h3>
      Your application's TeaCSS build. The package ships no stylesheet — `accordionRecipe` names the classes and your entry generates them.

      <h3>Can I restyle it?</h3>
      Every part takes `class`, and caller classes merge last.

```astro
---
import { Accordion, AccordionContent, AccordionItem, AccordionSummary } from "@teasim/astro/accordion";
---

<Accordion>
  <AccordionItem name="faq" open>
    <AccordionSummary><h3>Does this need JavaScript?</h3></AccordionSummary>
    <AccordionContent>No. The disclosure is the browser's.</AccordionContent>
  </AccordionItem>
  <AccordionItem name="faq">
    <AccordionSummary><h3>Where do the styles come from?</h3></AccordionSummary>
    <AccordionContent>Your application's TeaCSS build.</AccordionContent>
  </AccordionItem>
</Accordion>
```

## Examples

### One at a time

Give sibling Items the same non-empty `name` and the browser closes the open
one when another opens. The group name is **document-wide**, so a page with two
independent accordions needs two names.

      <h4>Green</h4>
      Two minutes, water just off the boil.

      <h4>Black</h4>
      Three minutes, water at a rolling boil.

Open at most one member of a named group initially — two Items sharing a name
and both carrying `open` is a state the browser has to resolve, and it closes
one of them for you.

### Several at once

Dropping `name` is not enough. `multiple` defaults to `false`, and on bind the
runtime keeps the first open Item and closes the rest — so two Items that both
carry `open` render as one open row. Pass `multiple` on the **root** to keep
them all.

      <h4>Ships no stylesheet</h4>
      The application's TeaCSS build generates every rule.

      <h4>Ships no client JavaScript</h4>
      For this family the open state is native; the runtime only adds focus and events.

```astro
<Accordion multiple>
  <AccordionItem open>…</AccordionItem>
  <AccordionItem open>…</AccordionItem>
</Accordion>
```

The two mechanisms are independent and both apply. `name` is the browser's,
and it works with scripting off; `multiple` is the runtime's, and it wins on
bind. Setting `multiple` while siblings share a `name` gets you the browser's
exclusivity anyway — use one or the other, not both.

## API reference

Four components, each rendering one native element.

| Component | Renders | Own props |
| --- | --- | --- |
| `Accordion` | `<div>` | `multiple`, `defaultValue`, `collapsible`, `orientation`, `loopFocus` |
| `AccordionItem` | `<details>` | `value` — plus native `open` and `name` |
| `AccordionSummary` | `<summary>` | none |
| `AccordionContent` | `<div>` | none |

### Accordion

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `multiple` | `boolean` | `false` | Several Items open at once |
| `defaultValue` | `string \| string[]` | — | Which `value` starts open; an array joins with commas |
| `collapsible` | `boolean` | `true` | The last open Item may close |
| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Which arrow keys move focus |
| `loopFocus` | `boolean` | `true` | Focus wraps at either end |

### AccordionItem

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `value` | `string` | — | Identifies the Item to `defaultValue` |
| `open` | `boolean` | `false` | Native `<details>` attribute |
| `name` | `string` | — | Native group name; siblings sharing one are mutually exclusive |

`AccordionSummary` must be the **first direct element child** of its Item —
that is a `<details>` requirement, not this component's. `AccordionContent`
renders a plain `<div>` and does not force a region landmark.

Each component owns `aria-controls`, `aria-disabled`, `aria-expanded` and
`role`, and `AccordionSummary` owns `tabindex` as well; passing any of them is
ignored rather than merged. Everything else native passes through.

### How the props reach the runtime

The five root props are not read by the server half. `Accordion` writes each as
a `data-*` attribute — `data-multiple`, `data-default-value`,
`data-collapsible`, `data-orientation`, `data-loop-focus` — and the runtime
reads them from the DOM on bind. That is why the markup is complete before any
script runs — the options travel as markup, not as a hydration payload.

The runtime itself is **not public API**. `@teasim/astro/accordion` exports the
four components and nothing else; the browser half is loaded by the component's
own `<script>`, which is the single edge between the two halves. Drive a bound
Accordion through events instead:

```ts
const root = document.querySelector('[data-slot="accordion/root"]');

// Listen: fires on the root whenever the open set changes.
root.addEventListener("accordion:change", (event) => {
  event.detail.value; // string[] — the open Items' values
});

// Drive: dispatch on the root, not on an Item.
root.dispatchEvent(new CustomEvent("accordion:set", { detail: { value: ["shipping"] } }));
```

Both carry `{ value }` rather than a bare array, and `accordion:set` is ignored
unless its target is the root itself. An Item needs a `value` for either
direction to name it.

### accordionRecipe

`accordionRecipe` exposes `root`, `item`, `summary`, and `content`. It lives on
`@teasim/astro/recipes`, never on the family subpath, so rendering an Accordion
never pulls a recipe in behind it.

```ts
import { accordionRecipe } from "@teasim/astro/recipes";

const classes = accordionRecipe();
classes.item({ className: "border-color:gray-600" });
```

---

# Code

Source: https://teasim.com/components/code.md

## Installation

The highlighting is Astro's own — the family wraps `astro/components/Code.astro`
rather than taking a Shiki dependency, and hands the frame, the header and the
copy button to `CodeBlock`. What a notation *means* is computation, so the
transformer set lives in `@teasim/astra`: `astra()` hands it to
`markdown.shikiConfig` for you, and you pass it to `<Code>` yourself because a
component is not part of that pipeline.

## Preview

```astro
---
import { Code } from "@teasim/astro/code";
import { codeTransformers } from "@teasim/astra/shiki";
---

<Code code={source} lang="ts" title="src/brew.ts" transformers={codeTransformers()} />
```

## Examples

### Line highlight

A range in the metastring marks the lines the paragraph is about.

### Diff

`// [!code ++]` and `// [!code --]` tint the line and sign it in the gutter the
padding already reserves.

### Focus

`// [!code focus]` dims and blurs everything else. Hovering the listing lifts
it again, so the surrounding code is still readable.

### Error and warning

### Line numbers

The gutter is a CSS counter on Shiki's own per-line spans, so it stays in step
with whatever else a transformer added or removed.

### Word highlight

### In markdown

`astra()` gives the same set to `markdown.shikiConfig`, so an ordinary fence
reads the same notation with nothing passed in. This one is a plain
` ```ts ` block — the frame around it is `CodeBlock`, which this site maps onto
markdown's `pre` so a fence and a `<Code>` read the same:

```ts
export function steep(minutes: number) {
  return minutes * 60; // [!code --]
  return minutes * 60_000; // [!code ++]
}
```

## API reference

| Prop | Type | What it does |
| --- | --- | --- |
| `code` | `string` | the source to highlight — required |
| `lang` | `string` | any language Shiki bundles; `plaintext` by default |
| `meta` | `string` | the metastring, where a `{2-4}` range or a `/term/` lives |
| `lineNumbers` | `boolean` | turns on the counter gutter |
| `transformers` | `ShikiTransformer[]` | what Shiki runs over the tree — `codeTransformers()` |
| `themes`, `defaultColor` | Shiki's own | GitHub's high-contrast pair with `defaultColor: false` by default |
| `title`, `language`, `copyable`, `copyLabel` | | forwarded to `CodeBlock` |

`codeRecipe` exposes `source` and takes a `numbered` selection.

---

# Cookie policy

Source: https://teasim.com/cookie-policy.md

## 1. Cookies used

None. This site sets no cookies of any kind — not necessary, not functional, not
analytical, not advertising.

## 2. Why there is no banner

Consent banners exist because sites store or read information that is not
strictly necessary. A static site that sets no cookies and runs no third-party
script has nothing to ask about, so it does not interrupt you to ask.

## 3. Local storage

One key, `teasim-theme`, holds your light or dark preference. It is not a
cookie: it is never transmitted with a request, and no server sees it. It is
written only when you operate the theme control.

## 4. Third parties

There are none embedded in the page. Fonts are self-hosted, code highlighting
happens at build time, and there is no embedded video, map or comment system.

## 5. Changes

If the example site ever gained something that stored information, this page
would describe it and the site would ask before storing it.

---

# DMCA policy

Source: https://teasim.com/dmca-policy.md

## 1. Scope

This site hosts documentation for open-source packages and does not accept
user-submitted content. There is nothing here that a third party could have
uploaded, so there is nothing to take down.

## 2. What a notice contains

A complete notice under this kind of policy identifies the work claimed to be
infringed, identifies the material said to infringe it precisely enough to be
found, gives the sender's contact details, and includes statements made in good
faith and under penalty of perjury.

## 3. Counter-notice

A policy of this kind describes the reply available to whoever posted the
material, and the period after which it is restored if no action follows.

## 4. Repeat infringers

Services that host user content commit to terminating accounts that infringe
repeatedly. A documentation site has no accounts.

## 5. Attribution

What this site does carry is [attributions](/attributions) for the software it
is built on, which is the more relevant document for a project of this kind.

---

# Teasim

Source: https://teasim.com/index.md

This site is built with the three packages it documents. The sidebar on every
reference page is computed by `createNavigation` from `@teasim/astra`; the
chrome around it comes from `@teasim/aster`, and every surface inside it from
`@teasim/astro`.

## The three packages

The split is what they produce, not how big they are:

| Package | What it gives you |
| --- | --- |
| `@teasim/astro` | The elements — 77 families that render markup and carry their behaviour. No stylesheet |
| `@teasim/aster` | The blocks — 15 page-level pieces that arrange those elements into a site's chrome |
| `@teasim/astra` | Everything that computes — navigation, schemas, validation, and the machine-readable routes |

Read [Project structure](/project-structure) for what a scaffolded project
contains and where the boundary falls, [Accordion](/components/accordion) for
what an element page looks like, and
[createNavigation](/references/create-navigation) for the data layer underneath
all of it.

## Built for agents too

Every page here has a markdown twin. Append `.md` to any address, or start from
the index the integration generates:

- [`/llms.txt`](/llms.txt) — every page as a link with its description
- [`/llms-full.txt`](/llms-full.txt) — the whole corpus as one document
- [`/index.md`](/index.md) — this page, as markdown

None of it is hand-maintained. `astra()` derives all three from the same
entries the sidebar is built from, so the corpus can never list a page the site
does not serve.

---

# A class the extractor never saw

Source: https://teasim.com/notes/a-class-the-extractor-never-saw.md

The frame puts small rotated squares at the corners of each band. They all
rendered at roughly `x = 0`, stacked on the left edge instead of sitting at the
four corners.

Nothing was wrong with the geometry. The component built its classes like this:

```ts
const corners = ["t", "t", "b", "b"];
const x = index < 2 ? "i-s" : "i-e";
const cls = `${x}:[var(--site-node-offset)]`;
```

## Why it produced no CSS at all

TeaCSS is a scanner, not a runtime. It reads your source **as text**, finds
whole class tokens, and generates a rule for each one it recognises. It never
executes the file.

So `` `${x}:[var(--site-node-offset)]` `` is not a class token as far as the
scanner is concerned. There is no `i-s:[...]` in the source text — only a
fragment starting at `:`. No rule is generated. The class still lands in the
HTML at runtime, matches nothing, and `inset-inline-start` falls back to `auto`.

The failure mode is the dangerous one: **no error**. A token that matches no
rule emits no CSS and no warning. The markup looks right, the class attribute
looks right, and the element is simply unstyled.

## The fix

Write the tokens out whole and pick between them:

```ts
const corners = [
  "i-t:[-3.5px] i-s:[var(--site-node-offset)]",
  "i-t:[-3.5px] i-e:[var(--site-node-offset)]",
  "i-b:[-3.5px] i-s:[var(--site-node-offset)]",
  "i-b:[-3.5px] i-e:[var(--site-node-offset)]",
];
```

Verbose, and correct. A test now asserts the literal strings are present and
that no `i-*:${` appears in the file, because the next person to tidy this into
a loop will reintroduce exactly the same bug.

## The general rule

Any class token that cannot appear literally in your source — because it is
composed at runtime, or comes from a CMS — has to be declared with
`@safelist` instead. Interpolation and utility scanners do not mix.

---

# A hairline that vanished in high contrast

Source: https://teasim.com/notes/a-hairline-that-vanished-in-high-contrast.md

The site's whole visual identity is hairlines: rails down both edges, a seam
between bands, small rotated squares at the corners, a hatched divider. In
Windows High Contrast Mode, one of them disappeared and the rest were fine.

## Why only one

Forced colours replaces a fixed set of properties with system colours:
`color`, `background-color`, `border-color`, `outline-color`, and a few more.
A border survives because `border-color` is replaced with `CanvasText`. A CSS
gradient survives because `background-image` is not in the list.

Every line in the frame was a border or a gradient — except the seam between
bands, which was a one-pixel `div` whose only paint was `background-color`.
Forced colours replaced it with `Canvas`, the same colour as the page behind
it. It did not fade; it became the background.

## The fix, and the thing that nearly made it useless

Naming a system colour is the whole fix:

```html
<span class="h:[1px] bg-color:gray-500 bg-color:[CanvasText]@forced-colors"></span>
```

But media queries carry **no specificity**. Both rules are a single class, so
whichever the stylesheet emits last wins. Had `bg-color:gray-500` come after
the forced-colors block, the fix would have been a no-op that still passed
every test — the class would be present, the CSS would exist, and the line
would still vanish.

It was worth checking rather than assuming. In the built stylesheet the base
utility sits at byte 102188 and the forced-colors rule at 126668, so the
system colour wins.

## What we did not fix

The footer carries a small decorative flourish, also painted with a background,
also erased in forced colours. We left it. The rule that decided it: **match
the design intent, not the pixel.** The seam is full strength and meant to be
seen, so its erasure is a regression. The flourish is a deliberate 28% wisp,
and repainting it `CanvasText` would not restore the intent — it would invert
it, turning a whisper into a crisp rule that reads as structure the design
never claimed.

## Since then

The background-painted seam is gone. Aligning the corner nodes forced a
stricter rule — every frame row draws the boundary as a border on its own
bottom edge — and a border was the only shape that put the line and the node on
the same pixel. So the fix described above is now redundant twice over: a
border is already replaced with `CanvasText`, and the seam names it anyway.
The reasoning survives the mechanism. A line's paint decides whether it exists
in forced colours, and the property you reach for is not a free choice.

---

# Duplication worth keeping

Source: https://teasim.com/notes/duplication-worth-keeping.md

A long cleanup removed redundancy across the packages. Nine candidates survived
on purpose. Each had been proposed by an independent review and rejected with a
reason — and without the reason written down, each would be proposed again.

## When merging would change behaviour

Two menu families have typeahead buffers that look identical. They are not: one
treats a single character as a fresh search, the other counts it as a repeat.
Merge them and the first keypress lands on a different item.

Nineteen accessible-name resolutions across the packages use three spellings
but only **two** behaviours: eleven pass `aria-labelledby` through a blank
check, eight do not. Unifying them decides what a blank string means, which is
an API choice wearing a refactor's clothing.

## When merging would hide a defect

Two files call a twenty-millisecond timer `waitForRaf`. It is not a frame.
Folding it into the real frame helper does not fix the misnomer — it buries it
somewhere the next reader will trust it.

A keyboard table looks like it is missing right-to-left handling. It is not:
a capture-phase listener intercepts the arrows first when direction is RTL and
stops propagation, so the table below never sees them. Substituting one for the
other is behaviour-identical and costs a reader the reason two layers exist.

## When the abstraction costs more than the copies

Around forty presentational wrappers are the irreducible shape of a component
library under these conventions. Eight teardown blocks share two lines. An icon
size ramp repeats across recipes.

## The habit

The output of a cleanup is not only the diff. It is the **list of things you
decided not to change, and why** — otherwise the same review runs again in six
months, reaches the same conclusions, and this time nobody remembers the
reason.

A decision that produces no diff leaves no trace in the repository. Where it
matters, pin it with a test that asserts the current shape and names the reason
in its title.

---

# Measure before you believe the audit

Source: https://teasim.com/notes/measure-before-you-believe-the-audit.md

Colours in this project are `oklch()` and `oklab()` with alpha, so contrast
cannot be checked by parsing strings. The obvious approach is to paint them:
fill a one-pixel canvas with the element's background, then the text colour,
and read the pixel back.

Done that way it reports badges failing at 3:1 that actually pass at 10:1.

## Why

A tinted badge's own background is something like an 8% wash. Fill only that
onto a transparent canvas and you get an 8% wash over nothing, which reads back
as near-black. Every light-on-tint pairing then looks broken.

The element's real background is the **whole ancestor stack** — the page
colour, then each non-transparent ancestor from outermost inward, then the
element's own tint. Composite all of it, and the numbers become real.

## What it caught once it was honest

The corrected audit found one thing the eye never would: every code comment on
the site at **3.92:1** in dark mode, and eleven light-mode tokens under 4.5,
straight from the default syntax theme. Swapping to the high-contrast pair put
the worst token at 4.91 light and 8.90 dark across 130 measured tokens.

## Two rules that came with it

Skip anything under an `aria-hidden` ancestor, not just the leaf — a decorative
wordmark at 9% opacity is not a contrast failure, and it will otherwise
dominate the report.

Measure in a separate step from the click that changed the theme. Computed
styles are stale within the same task, so a same-step measurement reports the
*previous* theme's colours with total confidence.

## The general point

An audit that reports failures is not evidence of failures. It is evidence
about the audit. The first thing to check when a tool says everything is broken
is whether the tool is measuring what you think it is — and the cheapest way to
find out is to run it against a case whose answer you already know.

---

# Name the thing focus lands on

Source: https://teasim.com/notes/name-the-thing-focus-lands-on.md

A code block that scrolls sideways needs a tab stop, or a keyboard user cannot
reach the rest of the line. Both of ours had one. Neither said what it was.

## Finding it by class, not by instance

The interesting move was not fixing the code block. It was asking what *else*
had the same shape. Every element in the package that renders `tabindex="0"`:

| Component | Role | Named |
| --- | --- | --- |
| `scroll-area/root` | `region` | yes, required |
| `table/container` | `region` | yes, required |
| `tabs/content` | `tabpanel` | yes |
| `context-menu/trigger` | `group` | yes |
| `code-block/body` | none | **no** |
| `carousel/content` | `group` | **no** |

Two gaps, not one. The carousel was the better find: its root names itself and
carries `aria-roledescription="carousel"`, each slide names itself and carries
`slide`, and the focusable scroll viewport between them announced a group and
nothing else.

## The worst case is the empty one

For the code block, the case that turns this from polish into a real gap is the
one with no title, no language, and copying switched off. The header is omitted
entirely, so the `figure` has no `figcaption` and therefore no name either. The
name on the body is then the only name anywhere in the subtree.

## The rule that came out of it

**The outer element carries the consumer's name; the inner scroll container
says what is inside it.** A code block's figure is named by its title, and the
body is named "Code" or "bash code". A carousel is named "Featured products" by
whoever placed it, and the viewport is named "Slides".

That is why the inner name is derived rather than required. Ask the consumer
for a second name and there are only two things they can write: the outer name
again, which is a duplicate announcement, or the default spelled out by hand.
Requiring it buys redundancy or boilerplate, never information.

---

# Region or group — let the count decide

Source: https://teasim.com/notes/region-or-group-let-the-count-decide.md

Having decided a scrollable code block needs a role and a name, the obvious
move was to match its siblings. `scroll-area/root` and `table/container` both
use `role="region"`. So: `region`.

That was wrong, and the way to find out was to count.

## What the pages actually contain

```txt
/components/code    13 code blocks, 1 with a title,  2 with a language
/index               4 code blocks, 0 with a title,  0 with a language
```

A `region` is a landmark. It appears in the landmark list that screen-reader
users navigate by. Ten of the thirteen blocks on one page would have been
landmarks named "Code" — the same name, ten times, in the list meant to help
you skip around the page.

That is not a smaller version of a good outcome. It is a worse outcome than
having no landmark at all.

## The axis that actually matters

The siblings are regions for a reason that does not generalise: a data table or
a scroll panel is **one prominent thing**, deliberately placed, and its name is
a required prop the consumer must supply. A code block **names itself** and a
documentation page renders one per fence.

Same runtime, same tab stop, opposite frequency — and frequency is the axis
that picks `region` from `group`. `group` names the tab stop and stays out of
the landmark list.

"The other two are regions" is consistency of implementation, not consistency
of situation.

## Two passes, one answer

A second reviewer reached `group` independently, before seeing the count, on
the required-prop-versus-self-naming argument. Two routes to the same call is
a better signal than either one alone — and it is the kind of check worth
setting up deliberately when a decision has no test that can fail.

---

# The build that ran twice

Source: https://teasim.com/notes/the-build-that-ran-twice.md

The repository has one gate: `bun run verify`. It runs formatting, types,
audits, a build, both examples, the tests, and a static Storybook. It took
about two minutes, and roughly fifteen seconds of that was pure waste.

## Finding it

The script chain read:

```txt
check → typecheck → audit → build → example → test → docs:build
```

and `docs:build` was itself defined as `bun run build && storybook build`. So
`build` ran, five steps happened, and then `build` ran again.

## Proving it was safe to remove

The interesting question is not whether the second build is redundant but
whether anything between the two writes into `dist`. Rather than reason about
it, hash it:

```bash
find packages/*/dist -type f -exec shasum -a 256 {} \; | sort -k2 | shasum -a 256
```

Take that digest, run `example` and `test`, take it again. Identical. Nothing
in between touches the build output, so the second build could only reproduce
what was already there.

## The fix

Split the Storybook step out under its own name and let the gate call that,
leaving `docs:build` to keep its documented contract for anyone running it
alone. Two minutes became one minute forty.

## The part worth keeping

The digest is the point. "Nothing else writes there" is the kind of claim that
is obviously true right up until a build step gains a side effect, and it costs
one command to stop guessing.

---

# The dev server that died on every build

Source: https://teasim.com/notes/the-dev-server-that-died-on-every-build.md

For weeks the workflow had a superstition in it. Rebuild a package, and the
running dev server would start returning 500s — `Could not import
./CodeBlock.astro` — and stay broken until you killed it, deleted
`node_modules/.vite`, and started again.

## What was actually happening

The build tool cleans before it writes, and its clean is a glob:

```txt
Cleaning 4311 files
```

So a rebuild **deletes every `.js`, `.d.ts`, `.astro` and `.css` in `dist`**
and puts them back a second later. The dev server watches that directory
through the workspace symlink. It sees four thousand deletions, tries to
re-resolve a module that no longer exists, fails — and **caches the failure**.
The files returning a second later change nothing, because nothing invalidates
the cached failure.

That is why deleting the cache was the only thing that ever worked.

## The fix

Stop watching the directory that is guaranteed to churn:

```js
vite: {
  server: { watch: { ignored: ["**/packages/*/dist/**"] } },
}
```

Verified by firing twenty-five requests at the previously-failing module
*during* a rebuild. All 200.

## What did not work

`resolve.preserveSymlinks: true` would have avoided the out-of-root path
entirely, and it breaks the framework's own module resolution under this
package manager's store layout.

Changing the build's clean step was the other candidate, and it is worse than
it looks: without the glob clean, a renamed output lingers in `dist` forever.

## The trade-off, stated plainly

A package change now needs the dev server restarted before it appears. Before,
it needed a restart *and* a cache deletion *and* it crashed first. The site's
own files still hot-reload.

---

# The gate has to actually gate

Source: https://teasim.com/notes/the-gate-has-to-actually-gate.md

The repository has one rule before merging: `bun run verify` must pass. It has
been defeated twice, in two different ways, and neither involved the checks
themselves being wrong.

## Once through a pipe

```bash
bun run verify | grep -E "error|fail"
```

The exit code of a pipeline is the exit code of its **last** command. `grep`
found nothing, exited 0, and the `&&` chain sailed on to the merge. A failing
test had been sitting in the output the whole time.

## Once through a semicolon

```bash
cat "$OUTPUT" ; git merge --no-ff branch && git push
```

Reading the result and acting on the result are not the same thing. `cat`
succeeded, so the merge ran — against a branch whose verify had exited 1 in
zero seconds because the formatter rejected a quote style.

Both times the check worked perfectly. Both times nothing was listening.

## The shape that cannot fail this way

Make the exit code the condition, in the same command:

```bash
bun run verify > verify.log 2>&1
E=$?
if [ $E -eq 0 ]; then
  git merge --no-ff -q branch && git push -q
else
  echo "NOT MERGED"; tail -25 verify.log
fi
```

## The part that generalises

A verification step you read with your eyes is not a gate; it is a report. The
difference only shows up on the day the report says something you were not
expecting, which is exactly the day you are moving quickly and skim it.

If a check is meant to block, something other than your attention has to be
doing the blocking.

---

# Two packages, one line

Source: https://teasim.com/notes/two-packages-one-line.md

Most component libraries make two decisions for you. They decide how your site
**looks**, by shipping a stylesheet. And they decide how your site is
**built**, by rendering your content.

Both feel like conveniences on day one. Both are expensive to undo in year two,
when you want something the library did not anticipate and the only paths open
are to fight it, fork it, or leave.

## Where the line falls

`@teasim/astro` renders markup and carries behaviour with it. It ships no CSS.

`@teasim/astra` computes navigation, validates content and serves the
machine-readable routes. It renders nothing.

Neither knows what the other looks like. A project can take either half alone —
the elements without the content layer, or the content layer under a completely
different set of components.

## What the split costs us

Two packages is more surface than one. Two changelogs, two dependency graphs,
and a boundary that has to be defended every time something would be *slightly*
easier if the content layer knew about the components.

There is a rule for that: the packages take external dependencies on different
terms — the element package takes none at all — and where a feature needs one,
the need decides which package it belongs to, not convenience.

## What it buys

A stylesheet you own. An accordion that is a `details` element, so it works
before the JavaScript arrives and keeps working if it never does. And an exit:
because nothing here is a wrapper around a widget, replacing one family with
your own is a local change, not a migration.

The measure of the split is not how much it helps on day one. It is how little
it costs on the day you want to leave.

## A postscript

Written when there were two. The rendering half has since been cut once more,
along the same kind of line: `@teasim/astro` is the elements, and
`@teasim/aster` is the page-level chrome composed from them — so a project that
wants a Button never installs a documentation shell. The argument is unchanged;
it simply applied a second time.

---

# Privacy policy

Source: https://teasim.com/privacy-policy.md

## 1. What this site collects

Nothing. The site is a set of static files. There is no analytics script, no
tag manager, no advertising pixel, and no server-side session.

## 2. What is stored in your browser

One value, under the key `teasim-theme`, recording whether you chose light or
dark. It is set only when you use the theme control, it never leaves your
device, and clearing site data removes it.

If you have not chosen a theme, nothing is stored and the site follows your
operating system's setting.

## 3. Fonts

IBM Plex Sans and IBM Plex Serif are self-hosted, downloaded at build time and
served from this origin. No request goes to a font provider while you read the
page, so no third party sees your address.

## 4. Requests the page makes

The page loads its own HTML, one stylesheet, its fonts, and a small amount of
JavaScript for the theme control and component behaviour. It makes no
cross-origin requests at all.

## 5. Cookies

None. See the [cookie policy](/cookie-policy) for the longer version of that
sentence.

## 6. Your choices

Because nothing is collected, there is nothing to request, correct or delete.
The theme preference is under your control in the browser.

## 7. Contact

A real policy names a controller and a contact route. This is an example site
and names neither.

---

# @teasim/aster

Source: https://teasim.com/products/aster.md

## What it is

The furniture a content site repeats on every page: the three-pane
documentation shell, the sticky header run, the footer, the navigation tree,
the pager, the pricing section, the question list, the closing call to
action, the sign-in panel, the request and response blocks, and the listing
shapes — steps, headings, grids, records.

Each one is composed from `@teasim/astro` elements rather than drawn from
scratch, and they are imported exactly the same way.

## The line it holds

**A block owns arrangement.** Grid, gap, measure, and the breakpoints where a
layout changes. It never restates a surface — a border, a fill, a type scale or
a focus ring arrives with the family it composes, so a look the elements lack is
fixed on the element and not patched here.

That line is why the package declares no `@shortcut` of its own. Every fragment
its recipes name is declared once, in astro's TeaCSS interface.

## Two invariants that bend here

An element renders no sibling part and takes no named slot. A block bends both,
and only where the shape demands it: a tree renders itself, so the nav renders
its own list part; and a layout has regions, so the shell takes its three panes
and the header takes its logo as named slots.

Both exceptions are pinned by tests rather than left as an allowlist with no
reason attached.

---

# @teasim/astra

Source: https://teasim.com/products/astra.md

## What it is

The half of a documentation site that has nothing to do with how it looks.
It reads a content collection and computes the structure — the sidebar tree,
the breadcrumb trail, the previous and next links, the table of contents.

## Why it is separate

A content helper that also renders markup decides how your site is built. That
is the second borrowed decision, and it is why computing is a separate package
from rendering rather than shipped inside it. `@teasim/astra` renders nothing,
and `@teasim/astro` and `@teasim/aster` know nothing about content. Either half
works on its own.

## Markdown twins

Every page is served twice: once as HTML for people, once as markdown for
machines. `/about` has `/about.md` beside it, and the site publishes `llms.txt`
and `llms-full.txt` so a model can read the whole thing without parsing your
markup.

## Validation that names the page

Schema problems are reported in dev with the slug that caused them. A missing
title, a link that points nowhere, a `prev` that names a page that does not
exist — each one is a console line naming the file, not a build failure.

---

# @teasim/astro

Source: https://teasim.com/products/astro.md

## What it is

A component library that renders semantic HTML and stops there. An accordion is
a `details` element. A dialog is a `dialog` element. The exclusive-group
behaviour when accordion items share a name is the browser's, not a script's.

## What it refuses to do

It ships no stylesheet. A library that ships CSS decides how your site looks,
and that is a borrowed decision that is expensive to undo. Instead every family
exposes a named recipe — `accordionRecipe`, `buttonRecipe` — whose parts you can
override, and caller classes merge last.

It also takes **no external dependencies**. Not a utility library, not a focus
trap, not a positioning engine. Where a browser primitive exists the package
uses it, and where one does not the behaviour lives in a small shared runtime.

## The shape of a family

Every family follows the same conventions, so learning one teaches the rest:

- Elements are found by `data-slot="family/part"`, never by class.
- Variants are named the same words across families — a button, a badge and an
  alert all answer to `primary`, `outline`, `ghost`.
- Anything focusable has an accessible name and a visible focus ring that
  clears 3:1 against the surface behind it.

---

# Project structure

Source: https://teasim.com/project-structure.md

A scaffolded Teasim project is an ordinary Astro project. Everything you will
edit is a real file in your repository; all three packages stay dependencies
and are never copied in.

## What lands in your repository

```text
my-docs
├── astro.config.mjs
├── index.css
├── package.json
├── tsconfig.json
└── src
    ├── content.config.ts
    ├── content
    │   └── docs
    │       ├── index.mdx
    │       └── brewing.md
    ├── helpers
    │   └── docs.ts
    └── pages
        └── [...slug].astro
```

| Path | What it is |
| --- | --- |
| `index.css` | The TeaCSS entry — presets, `@source` globs, `@teacss;`. This file **is** the configuration; there is no `teacss.config.*` |
| `astro.config.mjs` | `teacss()` and `astra()`, plus `markdown.shikiConfig`, `prefetch`, and `vite.resolve.noExternal` |
| `src/content.config.ts` | The `docs` collection, from astra's `docsCollection()` |
| `src/content/docs/` | Your pages. The tree here is the site |
| `src/helpers/docs.ts` | The glue: collection entries in, navigation data out |
| `src/pages/[...slug].astro` | One route for every page, and the landing page too — there is no separate `index.astro` |

Ten files, two of them seed content. One `.md` and one `.mdx` on purpose: the
pair proves both parse paths the moment the dev server starts.

## The tree is the structure

The directory layout under `src/content/docs/` is the URL structure and the
sidebar. **The path is the structure** — `guides/installing` nests under
`guides` whether or not `guides` is a page in its own right.

```text
src/content/docs
├── index.mdx            →  /
├── project-structure.mdx →  /project-structure
├── components
│   └── accordion.mdx    →  /components/accordion
└── references
    └── create-navigation.mdx
```

A directory with no entry of its own becomes a heading in the sidebar: its
`slug` and `href` are `null`, it is not navigable, and it takes its label from
the path segment, title-cased. That is why **Components** and **References**
appear in the rail on the left without being pages.

Move a file and its route and its sidebar entry move with it. Frontmatter
handles the fine grain — `sidebar.order`, `sidebar.badge`, `draft` — but the
shape of the site comes from the filesystem. There is no second navigation
config to keep in sync, so the site cannot drift from its own contents.

## What is yours and what is not

The three packages divide by what they produce:

| Package | Ships | Knows about |
| --- | --- | --- |
| `@teasim/astro` | elements — Button, Dialog, Prose | behaviour and accessibility |
| `@teasim/aster` | blocks — SiteShell, SiteNav, SitePricing | arrangement |
| `@teasim/astra` | data helpers, the Astro integration, the CLI | your content |

The direction is one-way: aster composes astro, your page composes both, and
astra imports neither. **astra computes, astro draws, aster arranges, the page
glues** — which is why `PackageManagers` takes commands already translated
rather than importing astra's `translatePackageCommand` itself.

Nothing is vendored. There is no upstream theme to override and no copy in your
repository to diff against, so upgrading the chrome is `npm update`.

## What the integration adds

`astra()` in your Astro config injects three routes you never write:

| Route | Contents |
| --- | --- |
| `/llms.txt` | The sidebar flattened to links and descriptions |
| `/llms-full.txt` | Every page body as markdown, slug-ordered |
| `/[...slug].md` | One page body as markdown |

They are wired together on purpose: an agent reads `/llms.txt`, follows a link,
and gets markdown rather than HTML it has to strip. Try
[`/llms.txt`](/llms.txt) or the markdown twin of this page,
[`/project-structure.md`](/project-structure.md).

To take one over, create the file — `src/pages/llms.txt.ts` and that route is
yours, no option required.

## What is not in the tree

`.astro/` is generated: content-collection types and the resolved config. It is
gitignored, and nothing in it is yours to edit.

There is no config file of astra's own. Everything it needs is an option on the
`astra()` call, and nothing else in the project reads one — including `site`,
which stays on Astro's `defineConfig` because the sitemap, the canonical URL,
and `Astro.site` all read it from there.

---

# createNavigation

Source: https://teasim.com/references/create-navigation.md

Creates a `Navigation` over a list of content entries. It builds the sidebar
tree a single time and binds the four lookups a page needs to that one tree, so
the rail, the breadcrumbs, and the pager can never disagree about what the site
contains.

```ts
import { createNavigation } from "@teasim/astra";

const docs = createNavigation(entries, { base: "/docs" });

docs.sidebar;                              // the tree, as getSidebar builds it
docs.prevNext("guides/installing");        // { prev, next }
docs.breadcrumbs("guides/installing");     // [{ label, href, current }, …]
docs.sections("guides/installing");        // top level, with the current one marked
docs.find("guides/installing");            // one node, or null

// prevNext reads the entry's own frontmatter, so a page hand-wires nothing.
docs.prevNext("intro");                    // honours `next: false` in intro's frontmatter

// An explicit override still wins.
docs.prevNext("intro", { next: "guides/installing" });

// Nothing here reads astro:content, touches the filesystem, or needs a build.
createNavigation([{ slug: "a", title: "Alpha" }]).sidebar[0].href; // "/a"
```

## API Reference

### Signature

```ts
createNavigation(entries: readonly ContentEntry[], options?: SidebarOptions): Navigation;
```

### Parameters

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `entries` | `readonly ContentEntry[]` | Yes | Usually `collection.map(toContentEntry)`. Order is not significant — the tree sorts by `sidebar.order`, then label |
| `options` | `SidebarOptions` | No | `base`, `trailingSlash`, `includeDrafts`, `transform` |

#### SidebarOptions

| Option | Type | Default | Notes |
| --- | --- | --- | --- |
| `base` | `string` | `"/"` | Prefix for every `href`; a path or an absolute URL. A path with no leading slash is still rooted |
| `trailingSlash` | `boolean` | `false` | Append `/` to every `href` except the root |
| `includeDrafts` | `boolean` | `false` | Keep entries marked `draft` |
| `transform` | `(nodes: SidebarNode[]) => SidebarNode[]` | — | Reshape the finished tree |

### Returns

Returns a `Navigation` — the tree plus four lookups bound to it.

| Member | Type | Notes |
| --- | --- | --- |
| `sidebar` | `SidebarNode[]` | The finished tree, already sorted and pruned |
| `find(slug)` | `SidebarNode \| null` | `null` for a heading, an unknown slug, or an empty one |
| `breadcrumbs(slug)` | `Breadcrumb[]` | Ancestry, `current: true` on the last crumb; `[]` for an unknown slug |
| `prevNext(slug, overrides?)` | `PrevNext` | Both ends `SidebarLink \| null`; never wraps |
| `sections(slug)` | `SidebarSection[]` | The top level, with the one holding `slug` marked `current` |

### Throws

**Nothing.** Bad content does the most sensible thing and carries on — two
entries that normalise to one slug become one node, last wins. That is how a
duplicate slug becomes one silently missing page, so run `validateContent` on
the same entries when you want the problems named instead — the scaffolded
`src/helpers/docs.ts` does exactly that, in dev only.

## Agent Contract

| Field | Value |
| --- | --- |
| Kind | factory |
| Canonical name | `createNavigation` |
| Aliases | None |
| Mutates input | No |
| Returns | `Navigation` |
| Reads `astro:content` | No |
| Needs a build | No |
| Configuration dependencies | None |
| Related | `getSidebar`, `getPrevNext`, `getBreadcrumbs`, `getSidebarSections`, `findSidebarNode` |

## Agent Notes

- Generate `createNavigation(entries, options)` for a page. The five underlying
  functions stay exported for a test driving one answer, or a page that wants
  one without the rest.
- Do not thread `{ prev: entry.data.prev, next: entry.data.next }` into
  `prevNext` — it reads the entry's frontmatter itself. A mapper that forgets
  makes those two schema fields silently inert.
- Build it once per page, not once per lookup. Each call rebuilds the tree.
- Map entries with `toContentEntry`, not by hand: a hand mapper that drops
  `externalLink`, `prev`, `next`, or `previousSlug` makes those fields inert and
  `validateContent` cannot report what it never receives.
- Both ends of `prevNext` are `SidebarLink`, whose `slug` and `href` are never
  `null`. Do not generate a null check for them.
- `breadcrumbs` keeps headings and `prevNext` skips them, so a trail is not a
  slice of the reading order. Do not derive one from the other.
- Pass `base: import.meta.env.BASE_URL` in an Astro project so every `href`
  survives a deploy under a subpath.

---

# Services

Source: https://teasim.com/services.md

## Scaffolding a site

`astra create` generates the routes, layouts and configuration for a
documentation site, by importing the packages rather than copying their source
into your repository. The output is small enough to read in a sitting.

## Adapting the system

The packages ship no stylesheet, which means adopting them is mostly a design
exercise: deciding the tokens, the type scale, the density, and how much frame
you want. The example site on this domain is one answer to that; it is not the
only one, and none of it is baked into the components.

## Accessibility review

Every family is checked in both themes for contrast against the composited
ancestor stack, for accessible names on interactive elements, for focus rings
that clear 3:1 against the surface behind them, and for keyboard reachability of
anything that scrolls.

That review is part of the packages, not an add-on. What is worth doing
separately is the composed page — the inverted footer that puts a focus ring at
2.75:1, the anchor that lands behind a sticky header. Those only appear once the
pieces are assembled.

## What we do not offer

Hosting, analytics, or a content management system. The output is static files;
where they go is your decision, and nothing in the packages needs a server.

---

# Subprocessors

Source: https://teasim.com/subprocessors.md

## 1. Current list

Empty. A subprocessor is a third party that processes personal data on an
operator's behalf. This site collects no personal data, so there is none to
pass on.

## 2. What would appear here

A real list names each provider, what it does, where it processes data, and
under what transfer mechanism. It is usually a table with a "last updated" date,
because the commitment attached to it is normally advance notice of change.

## 3. Build-time services

Fonts are fetched from a font provider **at build time** and then self-hosted.
That means the provider sees the build machine once per build, and never sees a
reader. Code highlighting also happens at build time and reaches no network.

## 4. Hosting

Static files have to be served by something. A real list would name that
provider here, along with the regions it serves from, since it necessarily sees
reader IP addresses in its logs.

## 5. Changes

A real policy commits to a notice period before a subprocessor is added.

---

# Team

Source: https://teasim.com/team.md

## Small on purpose

Two packages with a defended boundary need a shared idea of where the boundary
is. That idea does not survive being distributed across a large group; it turns
into a document nobody reads and then into a boundary nobody enforces.

## How work is divided

By family, not by layer. Whoever builds an accordion builds its markup, its
recipe, its runtime, its stories, its tests and its documentation. There is no
handoff between "the component" and "the styles" because they are the same
decision.

## Review is adversarial on purpose

A second reader's job is to try to refute a change, not to approve it. The most
useful reviews on this project have been the ones that took a decision already
made and reached it again independently — or failed to, which is more useful
still.

Two reviewers agreeing after arriving separately is worth more than either one
alone, and it is the only check available for decisions no test can fail.

## What we do not do

Estimates against a calendar. The work is verification-bound, not
implementation-bound: writing a component takes an afternoon and proving it
behaves at 320 pixels, at 200% zoom, under forced colours, in right-to-left, and
without JavaScript takes considerably longer.

---

# Terms of service

Source: https://teasim.com/terms.md

## 1. About this document

This site is the example application shipped with the Teasim packages. It exists
to demonstrate the components and the content pipeline. The text below shows the
shape of a policy page in this design system; it is not a real agreement and no
service is being offered under it.

## 2. The software

The Teasim packages are published under the MIT licence. That licence, and not
this page, governs your use of the code. Where the two differ, the licence file
in the repository is the one that applies.

## 3. No warranty

The packages are provided as they are, without warranty of any kind. They are
pre-release: the version number is `0.0.0` and the public API is expected to
change without a deprecation period.

## 4. Acceptable use

See the [acceptable use policy](/acceptable-use-policies) for the shape of a
usage policy in this system.

## 5. Content

The notes and documentation on this site describe engineering decisions made
while building the packages. They are accurate as of their published date and
are not maintained as the code changes.

## 6. Changes

An example policy would describe how changes are communicated and when they take
effect. This one changes whenever the example site is rebuilt.

## 7. Contact

A real policy ends with a way to reach someone. This one ends by pointing at the
repository, which is where the packages and their issues live.

---

# Values

Source: https://teasim.com/values.md

## Usefulness over completeness

A family ships when it does one thing correctly, not when it covers every case
someone might want. Speculative props are harder to remove than to add, and an
API that anticipates everything commits you to all of it.

## Clarity over cleverness

The measure of a component is whether you can predict its DOM without reading
its source. Where a clever abstraction and an obvious repetition disagree, the
repetition usually wins — and where it does, the reason gets written down so the
next reader does not have to rediscover it.

## Craft over throughput

Details that only some people notice are still details. Focus rings that clear
contrast against the surface behind them, hairlines that survive forced colours,
anchors that clear a sticky header — none of these show up in a demo, and all of
them show up in use.

## Ownership over process

Whoever changes something is responsible for verifying it, including the parts
that are tedious to check. "The tests passed" is not ownership; the tests only
know what someone thought to ask.

## Calm over urgency

Nothing here auto-rotates, auto-plays, or animates without being asked. Motion
respects `prefers-reduced-motion`, and the default state of an interface is
still.

## Humility about being wrong

Half the notes on this site are about something we got wrong: an audit that
measured the wrong thing, a fix that would have been a no-op, a gate that never
gated. Writing those down is cheaper than rediscovering them.