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: errorpacks/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: nonepages/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