@@ -0,0 +1,79 @@
+# 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.