Duolith docs

packs

An app with its own styling pack (building on Duolith's) and components pack (decision 0160): rules duolith lint checks as W0100, skills and references for agents, and the AGENTS.md section and subagents duolith packs sync --agents writes. It lints clean; duolith packs lists its packs.

Run it

cargo run -p duolith-cli -- dev examples/packs     # live, reloads on save
cargo run -p duolith-cli -- build examples/packs   # static output in examples/packs/dist

The folder on the web: examples/packs.

Source

components/ui/AppButton.duo
---
// AppButton: the one button of this app, on brand. The components pack owns
// components/ui/, so this file may use the kit's Button that pages may not.
import { props } from "@duolith/client";
import { Button } from "@duolith/kit";

let { label, onPress } = props<{ label: string; onPress?: () => void }>();
---

<Button label={label} onPress={onPress} />
components/ui/Panel.duo
---
// Panel: a card on brand, with large corners.
import { props } from "@duolith/client";

let { title } = props<{ title: string }>();
---

<view class="p-4 gap-2 rounded-lg bg-surface border">
  <text class="text-heading text-ink">{title}</text>
  <slot />
</view>
duolith.yaml
# Project settings (decision 0080). A pack rule is set by its id (decision
# 0160): the pack says one-button is an error; this file could lower it.
lint:
  styling/large-corners: error
packs/components/pack.yaml
# The components pack: this app's own parts (decision 0160). It has the
# topic of Duolith's own components pack, so it builds on it: Duolith's
# rules stay, and these are added.
topic: components
description: Use when adding a button, a card or any other part to a screen of this app.
owns: [components/ui/**]
rules:
  - id: one-button
    says: Every button is components/ui/AppButton.duo, never the kit's Button.
    why: AppButton is the kit's Button on brand; a page using the kit's directly shows a blue button no one chose.
    level: error
    check:
      parts:
        deny: [Button]
        use: components/ui/AppButton.duo
    examples:
      bad:
        - code: |
            ---
            import { Button } from "@duolith/kit";
            ---

            <screen>
              <Button label="Save" />
            </screen>
          reports: [components/one-button]
      good:
        - code: |
            ---
            import AppButton from "../components/ui/AppButton.duo";
            ---

            <screen>
              <AppButton label="Save" />
            </screen>
  - id: cards-are-panels
    says: A card is components/ui/Panel.duo, never the kit's Card.
    why: Panel has the brand's surface, border and large corners; the kit's Card has none of them.
    check:
      parts:
        deny: [Card]
        use: components/ui/Panel.duo
    examples:
      bad:
        - code: |
            ---
            import { Card } from "@duolith/kit";
            ---

            <screen>
              <Card><text>Hi</text></Card>
            </screen>
          reports: [components/cards-are-panels]
      good:
        - code: |
            ---
            import Panel from "../components/ui/Panel.duo";
            ---

            <screen>
              <Panel title="Hi"><text>There</text></Panel>
            </screen>
  - id: parts-live-in-ui
    says: A reusable part of the app's look lives in components/ui/.
    why: The components pack owns components/ui/, so a button there is checked as one of the app's parts; one elsewhere is not, and is found by no one.
    check:
      files:
        name: "*Button.duo"
        folder: components/ui
    examples:
      bad:
        - file: components/SaveButton.duo
          code: |
            <view><text>Save</text></view>
          reports: [components/parts-live-in-ui]
      good:
        - file: components/ui/SaveButton.duo
          code: |
            <view><text>Save</text></view>
packs/styling/pack.yaml
# The styling pack: this app's look (decision 0160). Every rule says what,
# why and how it is checked, and its examples are compiled by
# `duolith packs test`, so the words cannot drift from what lint does.
topic: styling
description: Use when styling any screen or component of this app, so it stays on brand.
owns: [theme.yaml]
rules:
  - id: brand-colours-only
    says: Colour only with the brand tokens and the neutral roles (canvas, surface, raised, border, ink, muted); never the kit's primary or danger.
    why: The brand is pink on neutrals; the kit's primary blue makes a screen look like another app, and every screen should read as this one.
    check:
      tokens:
        color: [brand, on-brand, canvas, surface, raised, border, ink, muted]
        fix: Use bg-brand and text-on-brand for emphasis, text-muted for quiet text.
    examples:
      bad:
        - code: |
            <screen>
              <text class="text-primary">Hi</text>
            </screen>
          reports: [styling/brand-colours-only]
      good:
        - code: |
            <screen>
              <text class="text-brand">Hi</text>
            </screen>
  - id: large-corners
    says: Corners are rounded-lg, or rounded-full for round things; never the small radii.
    why: The brand's shapes are soft; one small corner beside the large ones looks like a mistake.
    check:
      classes:
        deny: [rounded-sm, rounded-md]
        replace: rounded-lg
    examples:
      bad:
        - code: |
            <screen>
              <view class="rounded-sm bg-surface"><text>Hi</text></view>
            </screen>
          reports: [styling/large-corners]
      good:
        - code: |
            <screen>
              <view class="rounded-lg bg-surface"><text>Hi</text></view>
            </screen>
  - id: no-style-blocks-in-pages
    says: Pages hold no style block; a look the utilities cannot give belongs in a component in components/ui/.
    why: A page's own CSS is seen by no other screen, so the same look gets written twice and drifts; a component in components/ui/ is shared and owned by the components pack.
    scope: [pages/**]
    check:
      style-blocks: { allow: false }
    examples:
      bad:
        - code: |
            <screen>
              <text class="hero">Hi</text>
            </screen>

            <style>
              .hero { letter-spacing: 0.1em; }
            </style>
          reports: [styling/no-style-blocks-in-pages]
      good:
        - code: |
            <screen>
              <text class="text-title">Hi</text>
            </screen>
  - id: no-hex-colours
    says: No colour is written as a value.
    why: A colour written out stays the same in dark mode and when the brand changes; its token follows both.
    check:
      lint: { hard-coded-colour: error }
    examples:
      bad:
        - file: components/Swatch.duo
          code: |
            <view class="swatch"><text>Hi</text></view>

            <style>
              .swatch { border-color: #be185d; }
            </style>
          reports: [W0061]
      good:
        - file: components/Swatch.duo
          code: |
            <view class="swatch"><text>Hi</text></view>

            <style>
              .swatch { border-color: var(--color-brand); }
            </style>
  - id: tone
    says: Headings are short and in sentence case; quiet text uses text-muted.
    why: Agents write long title-case headings unless told; the brand's voice is plain and short.
    check: none
pages/index.duo
---
import { state } from "@duolith/client";
import AppButton from "../components/ui/AppButton.duo";
import Panel from "../components/ui/Panel.duo";

let count = state(0);

function increment() {
  count = count + 1;
}
---

<screen title="Packs" class="p-6 gap-4 bg-canvas">
  <text class="text-title text-brand">On brand</text>
  <Panel title="Pressed {count} times">
    <text class="text-body text-muted">
      Every colour, corner and button here follows packs/styling and packs/components.
    </text>
    <AppButton label="Press me" onPress={increment} />
  </Panel>
</screen>
theme.yaml
# The brand's colours. The styling pack (packs/styling) lets screens colour
# only with these and the neutral roles, so every screen stays on brand.
color:
  brand: { light: "#be185d", dark: "#f9a8d4" }
  on-brand: { light: "#fff1f7", dark: "#3b0820" }

radius:
  lg: 14px