# CipherCell — build with the primitives, never with raw CSS

CipherCell's site is Astro. What ships here is the layer underneath it: fourteen React
primitives that emit exactly the classes the site's own stylesheet defines, plus the tokens
and the typeface. Styling lives in the stylesheet, not in the components, so a design built
from these parts cannot drift from the site, and its markup ports to `.astro` one to one.
Each component's `.prompt.md` gives that Astro equivalent.

## Wrapping

Every screen starts with `Surface`. It sets the paper ground, the typeface and the base
size; without it a design inherits the canvas defaults and none of CipherCell's typography.
`Surface` takes `tone="paper"` (the default) or `tone="night"`.

Inside it the order is `Section` → `Container` → `Grid` → `Col`. A `Section` carries the
vertical air. A `Container` holds the page margins and the maximum width. Nothing else may
set page margins.

There is no provider, no theme object and no load order to get right.

## The idiom

Compose from the components. Reach for your own CSS only for layout glue the primitives do
not cover, and then use tokens for every value: a raw hex or pixel value is a defect in this
system. Do not invent class names; the stylesheet has no utility classes and yours will not
resolve.

**Components.** `Surface`, `Section`, `Container`, `Grid`, `Col`, `Stack` for structure.
`Display`, `Heading`, `Text`, `Eyebrow` for type. `Button`, `TextLink` for actions.
`Prose`, `Rule` for content.

**Spacing.** Nothing carries its own margins, so two blocks placed together sit flush.
`Stack` is what separates them, and its `gap` is a step on the space scale, 1 to 9. Never
hand-roll a pixel gap.

**Tokens** for your own CSS: `--paper`, `--paper-deep`, `--ink`, `--ink-muted`, `--night`,
`--line`, `--overlay`; `--font-sans`; the sizes `--step-display`, `--step-h2`, `--step-title`,
`--step-h3`, `--step-body`, `--step-small`, each with a matching `--track-*` and `--leading-*`;
`--weight-regular` and `--weight-medium`, and no bold; `--space-1` … `--space-9`, `--section`,
`--gutter`, `--gap`, `--container`, `--measure`; `--radius` (0) and `--radius-sm` (2px);
`--hairline`; `--dur-fast`, `--dur`, `--dur-slow` and `--ease`.

**There is no accent colour, and there are no shadows.** Links and buttons work through
underline, weight and surface. Separation comes from a `Rule` or from a change of surface.
Inside a night surface the ink tokens flip themselves, so muted text, hairlines and buttons
all correct themselves with nothing to set.

## Where the truth lives

Read each component's `.prompt.md` before using it: it carries the usage judgment and the
Astro equivalent. `.d.ts` files carry the props. `styles.css` and its imports hold every token
and class definition. The written brief is in `guidelines/`, and it governs attitude, colour,
typography, layout, imagery, motion and language, including the patterns that are banned.

## Building with it

```jsx
<Surface tone="night">
  <Section spacing="tight">
    <Container>
      <Grid>
        <Col span={7}>
          <Heading>Security is built in,<br />not bolted on.</Heading>
        </Col>
        <Col span={4} start={9}>
          <Stack gap={5} align="start">
            <Text measure>Every interface between components is an attack surface.</Text>
            <Button href="/contact">Talk to us</Button>
          </Stack>
        </Col>
      </Grid>
    </Container>
  </Section>
</Surface>
```

Note what this does: the blocks sit asymmetrically rather than centred or evenly split, the
line break in the headline is placed by hand, the button names the action, and every value
that is not a grid position comes from a token.