homepage_relaunch/.design-sync/conventions.md

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

<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.