Colour theme

Card

  • Primitives

The card frame. A surface with three axes — border, padding, shadow — on article, section, li or div. It owns no typography: what speaks inside a card speaks through Heading and Text. Teaser wraps one and owns the combinations it permits.

Border

On this site every card is bordered unless it says otherwise: the theme file's card shape moves the default (the package's own is off). The line is the card style's border colour, so it follows the theme and the mode.

No prop — the site's card shape, bordered.

border={false} — the surface and the radius, no line.

astro
---
import Card from "tsugite/Card/Card.astro";
import Text from "tsugite/Text/Text.astro";
---
{/* Without the prop a card takes the project's card shape: this site's theme file
    draws every card with a border (ADR-0046, a moved default); the package's own
    default is none. The line is the card style's border colour, else the layer's
    border-1, so it follows the theme and the mode with everything else. */}
<Card>
  <Text text="No prop — the site's card shape, bordered." />
</Card>
<Card border={false}>
  <Text text="border={false} — the surface and the radius, no line." />
</Card>

Padding

Four steps, md by default — the package's and this site's card shape alike. Each resolves through a size token, so the padding grows with the tier.

padding none — the content meets the edge; for media that bleeds.

padding sm — a compact list item.

padding md — the default.

padding lg — a feature card with room to breathe.

astro
---
import Card from "tsugite/Card/Card.astro";
import Text from "tsugite/Text/Text.astro";
---
{/* Four steps, md by default. Each resolves through a --size-* token, so
    the padding grows with the tier — never a raw measure. Bordered here so
    the step reads. */}
<Card border={true} padding="none">
  <Text text="padding none — the content meets the edge; for media that bleeds." />
</Card>
<Card border={true} padding="sm">
  <Text text="padding sm — a compact list item." />
</Card>
<Card border={true}>
  <Text text="padding md — the default." />
</Card>
<Card border={true} padding="lg">
  <Text text="padding lg — a feature card with room to breathe." />
</Card>

Shadow

The values are the theme's shadow ramp, shadow-1, shadow-2 … (ADR-0051): each a geometry the ramp authors once, cast in the ink of the ground the card lies on — here the page's. A shadow added to the ramp is a value here, its gate generated. Every card states its depth: without the prop it carries data-shadow=&quot;none&quot;.

shadow-1 — barely lifted.

shadow-2 — clearly off the page.

shadow-3 — floating.

astro
---
import Card from "tsugite/Card/Card.astro";
import Text from "tsugite/Text/Text.astro";
---
{/* The theme's shadow ramp, one key each (ADR-0051). A card without a shadow prop
    carries data-shadow="none", so every card states its depth. */}
<Card shadow="shadow-1">
  <Text text="shadow-1 — barely lifted." />
</Card>
<Card shadow="shadow-2">
  <Text text="shadow-2 — clearly off the page." />
</Card>
<Card shadow="shadow-3">
  <Text text="shadow-3 — floating." />
</Card>

The card style, on the ground and in each theme

One card, no props, in five places. A card with no style takes the first, card-1, whose colours the theme creator sets per layer: on the ground it is the ground's, inside a theme that theme's. The card does not change; the layer it stands in does.

ground

card-1 on the ground.

theme-1

card-1 in theme-1.

theme-2

card-1 in theme-2.

theme-3

card-1 in theme-3.

theme-4

card-1 in theme-4.

astro
---
import Card from "tsugite/Card/Card.astro";
import Theme from "tsugite/Theme/Theme.astro";
import Text from "tsugite/Text/Text.astro";
import Caption from "tsugite/Caption/Caption.astro";

const themes = ["theme-1", "theme-2", "theme-3", "theme-4"];
---
{/* The same card, no props, wherever it stands. A Card with no data-surface takes
    the first surface style, card-1 (ADR-0043): its colours are set per layer in the
    theme creator, so on the ground it is the ground's card-1 and inside a theme that
    theme's. Nothing on the card changes; the layer it stands in does. */}
<div class="card-styles">
  <div class="card-styles-cell">
    <Caption size="sm" text="ground" />
    <Card>
      <Text text="card-1 on the ground." />
    </Card>
  </div>
  {themes.map((name) => (
    <Theme name={name} class="card-styles-cell">
      <Caption size="sm" text={name} />
      <Card>
        <Text text={`card-1 in ${name}.`} />
      </Card>
    </Theme>
  ))}
</div>

<style>
  /* Example chrome only: the air is the example's, never the Theme's. */
  .card-styles {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(min(14rem, 100%), 1fr));
    gap: var(--size-md);
  }

  .card-styles-cell {
    display: grid;
    gap: var(--size-sm);
    align-content: start;
    padding: var(--size-md);
  }
</style>

Shadow on a ground

A card's shadow mixes two tones: the ground it falls on and the card's own surface. A Theme publishes its ground's ink per shadow of the ramp, precomputed by the colour factory; the card adds a glow of its own surface through the valves of the theme it speaks, set per mode and per shadow. Where relative colour is missing, the ground's tone stands alone.

No theme of its own: the card is its ground's card-1, and both tones are the ground's.

theme-2 on this ground: the ground's ink, and a glow of theme-2.

theme-3 on this ground: the ground's ink, and a glow of theme-3.

No theme of its own: the card is its ground's card-1, and both tones are the ground's.

theme-2 on this ground: the ground's ink, and a glow of theme-2.

theme-3 on this ground: the ground's ink, and a glow of theme-3.

astro
---
import Card from "tsugite/Card/Card.astro";
import Theme from "tsugite/Theme/Theme.astro";
import Text from "tsugite/Text/Text.astro";

const grounds = ["theme-4", "theme-1"];
const cards = [
  { theme: undefined, text: "No theme of its own: the card is its ground's card-1, and both tones are the ground's." },
  { theme: "theme-2", text: "theme-2 on this ground: the ground's ink, and a glow of theme-2." },
  { theme: "theme-3", text: "theme-3 on this ground: the ground's ink, and a glow of theme-3." },
];
---
{/* A card's shadow mixes two tones. The first is the ground's ink, published by the
    Theme the card lies on. The second is a glow of the card's own surface, through the
    valves of its theme — per mode, turned down in dark. Here the theme is set on the card
    itself (data-theme), so the card is that theme's card-1 (ADR-0043). A card whose theme
    lives on a Theme inside it glows with its ground's tone, since a card cannot read what
    lies inside it. */}
{grounds.map((ground) => (
  <Theme name={ground} class="card-ground">
    {cards.map(({ theme, text }) => (
      <Card shadow="shadow-2" data-theme={theme}>
        <Text text={text} />
      </Card>
    ))}
  </Theme>
))}

<style>
  /* Example chrome only: the air is the example's, never the Theme's. */
  .card-ground {
    display: grid;
    gap: var(--size-md);
    padding: var(--size-2xl) var(--site-offset);
  }
</style>

Element

The markup shape is independent of the look. Cards as list items: the list owns the flow, the card owns the frame.

  • First item — a card as an li.

  • Second item — same frame, same shape.

  • Third item — the list owns the flow, the card owns the frame.

astro
---
import Card from "tsugite/Card/Card.astro";
import Text from "tsugite/Text/Text.astro";
---
{/* The element is the markup shape — div (default), article, section or li —
    and it is independent of the look. Three cards as list items. */}
<ul style="list-style:none; margin:0; padding:0; display:grid; gap:var(--size-sm);">
  <Card element="li" border={true} padding="sm">
    <Text text="First item — a card as an li." />
  </Card>
  <Card element="li" border={true} padding="sm">
    <Text text="Second item — same frame, same shape." />
  </Card>
  <Card element="li" border={true} padding="sm">
    <Text text="Third item — the list owns the flow, the card owns the frame." />
  </Card>
</ul>

A frame, not a voice

Card owns no typography. Heading and Text speak inside it; the card gives surface, gap and edge. A raw p in a card is unvoiced.

A frame, not a voice

The card sets the gap between these two runs and the edge around them. Their font, size and leading come from the family components, not from the card.

Quiet meta line — label voice, small.

astro
---
import Card from "tsugite/Card/Card.astro";
import Heading from "tsugite/Heading/Heading.astro";
import Text from "tsugite/Text/Text.astro";
import Caption from "tsugite/Caption/Caption.astro";
---
{/* Card owns no typography. What speaks inside it speaks through the family —
    Heading for the loud voices, Text for reading, Caption for the UI voice — and the card gives
    surface, gap and edge. A raw <p> in here would be unvoiced. */}
<Card border={true} padding="lg">
  <Heading text="A frame, not a voice" element="h3" size="4" />
  <Text text="The card sets the gap between these two runs and the edge around them. Their font, size and leading come from the family components, not from the card." />
  <Caption element="p" text="Quiet meta line — label voice, small." size="sm" />
</Card>

Combined — and the empty rule list

The axes combine freely. The list of forbidden border/shadow pairs is empty in Tsugite — a project rule, not a system one — so every combination is permitted until a project says otherwise.

border + shadow-1 — an outlined card that is also lifted.

border + shadow-3, padding sm — permitted, whether or not a project would want it.

astro
---
import Card from "tsugite/Card/Card.astro";
import Text from "tsugite/Text/Text.astro";
---
{/* The axes combine freely. The list of forbidden (border, shadow) pairs
    is EMPTY in Tsugite — a project rule, not a system one — so every
    combination is permitted until a project says otherwise. Teaser is the
    consumer that actually owns its permitted combinations. */}
<Card border={true} shadow="shadow-1" padding="lg">
  <Text text="border + shadow-1 — an outlined card that is also lifted." />
</Card>
<Card border={true} shadow="shadow-3" padding="sm">
  <Text text="border + shadow-3, padding sm — permitted, whether or not a project would want it." />
</Card>

Three renderers, one recipe

The contract is the rendered DOM. lib/card.ts resolves the props; Card.astro, Card.tsx and Card.vue write the same class and data-* attributes, and the same CSS gates on all of them.

Rendered by Card.astro.

Rendered by Card.tsx.

Rendered by Card.vue.

astro
---
import Card from "tsugite/Card/Card.astro";
import CardReact from "tsugite/Card/Card.tsx";
import CardVue from "tsugite/Card/Card.vue";
import Text from "tsugite/Text/Text.astro";
---
{/* One recipe (lib/card.ts), three renderers. Both write the same root class and the
    same data-* attributes, so the same CSS gates on all of them. React and Vue
    render on the server here; no client directive, no hydration. */}
<Card border={true} padding="md" shadow="shadow-1" data-renderer="astro">
  <Text text="Rendered by Card.astro." />
</Card>
<CardReact border={true} padding="md" shadow="shadow-1" data-renderer="react">
  <p class="Text" data-voice="body" data-size="md" data-align-inline="start" data-wrap="pretty" data-cap-inline="true" data-text-box="block">
    <span class="text">Rendered by Card.tsx.</span>
  </p>
</CardReact>
<CardVue border={true} padding="md" shadow="shadow-1" data-renderer="vue">
  <p class="Text" data-voice="body" data-size="md" data-align-inline="start" data-wrap="pretty" data-cap-inline="true" data-text-box="block">
    <span class="text">Rendered by Card.vue.</span>
  </p>
</CardVue>

Test bench

The Card fixture — border, padding, shadow and their combinations, mounted unchanged.

Card

Border

No border

border="false" (default)

Bordered

border="true"

Shadow

Shadow shadow-1

shadow="shadow-1"

Shadow shadow-2

shadow="shadow-2"

Shadow shadow-3

shadow="shadow-3"

Padding

None

padding="none"

Small

padding="sm"

Medium

padding="md" (default)

Large

padding="lg"

Combined

Border + shadow

border="true" shadow="shadow-1" padding="lg"

Floating card

shadow="shadow-2" padding="lg" element="div"