# Groundwork

> The groundwork for designing and building apps, sites, CLIs, terminal UIs, Omarchy panels and agents.

## Docs

- [Groundwork](https://groundwork.timmo.dev/): The groundwork for designing and building apps, sites, CLIs, terminal UIs, Omarchy panels and agents.
- [Principles](https://groundwork.timmo.dev/principles): The rules every part of Groundwork follows, from data-first themes to agents reading and using it.
- [Targets](https://groundwork.timmo.dev/targets): One theme document and one set of roles, with a generator for each kind of app.
- [Behaviour](https://groundwork.timmo.dev/behaviour): How CLIs, agent tools, progress, status and notifications behave, so every tool works alike.
- [Sync](https://groundwork.timmo.dev/sync): How components and token files reach apps as copies, and how edits travel back.
- [Roadmap](https://groundwork.timmo.dev/roadmap): What's built, what's next, and where the plan is tracked.

## Foundations

- [Foundations](https://groundwork.timmo.dev/foundations): The three layers of tokens, from colour scales to purpose roles to each target's output.

- [Colour](https://groundwork.timmo.dev/foundations/colour): The colour roles every theme fills, how they're solved in OKLCH, and the contrast targets they meet.
- [Type](https://groundwork.timmo.dev/foundations/type): Fonts, bundled through Fontsource so they show everywhere, and the type scale.
- [Layout](https://groundwork.timmo.dev/foundations/layout): Spacing, radius, motion, elevation and focus, the foundations shared by every theme.

## Themes

- [Themes](https://groundwork.timmo.dev/themes): Base and five themes, each a small data document solved into light, dark and Darker.

- [Base](https://groundwork.timmo.dev/themes/base): Neutral surfaces with a slight blue-grey tint, black and white primaries, and links as strong text. What every theme builds on.
- [Glazing](https://groundwork.timmo.dev/themes/glazing): Cool periwinkle, like glass and Tokyo Night. Large radii, faint borders and a glassy sheen.
- [Survey](https://groundwork.timmo.dev/themes/survey): Charcoal with surveyor's marker pink. Boxy, thick borders, bold weights and a marker bar.
- [Slate](https://groundwork.timmo.dev/themes/slate): Welsh slate's purple-grey with a mauve accent. Round, with pill buttons and soft borders.
- [Bridge](https://groundwork.timmo.dev/themes/bridge): A clear, bright blue on neutral charcoal. Medium radii, soft borders and pill chips.
- [Snag](https://groundwork.timmo.dev/themes/snag): Warm amber on near-black. Compact and table-first, with square badges.
- [Optional themes](https://groundwork.timmo.dev/themes/optional): Catppuccin and Tokyo Night, mapped onto the roles so they stay faithful to their palettes. Apps opt in.
- [Contrast report](https://groundwork.timmo.dev/themes/contrast): Every theme role measured against its contrast target on the raised surface, in light, dark and Darker.
- [Writing a theme](https://groundwork.timmo.dev/themes/writing-a-theme): The theme document format, checked against a Schema so an agent can write one.

## Conventions

- [Conventions](https://groundwork.timmo.dev/conventions): The four kinds of repository, how issues and Discussions work in each, and where the label manifest lives.

- [Labels](https://groundwork.timmo.dev/conventions/labels): The label sets in Title Case, each with a description and a colour distinct within any repository.
- [Repositories](https://groundwork.timmo.dev/conventions/repositories): Every public repository's kind, how many labels it takes, and its own area labels.

## Components

- [Live demo](https://groundwork.timmo.dev/components/demo): The first Lit component on the base, running on the page through an Astro Demo component.

## Agent skills

- [groundwork](https://groundwork.timmo.dev/.well-known/agent-skills/groundwork/SKILL.md): Read the Groundwork docs instead of answering from memory. The groundwork for designing and building apps, sites, CLIs, terminal UIs, Omarchy panels and agents. Use when a task involves Groundwork: how it works, how to set it up or configure it, or its API.

## Agent resources

- [llms-full.txt](https://groundwork.timmo.dev/llms-full.txt): The full Markdown of every page in one file.
- [Page Markdown](https://groundwork.timmo.dev/index.md): Append `.md` to any page URL to fetch that page as raw Markdown.
- [JSON API](https://groundwork.timmo.dev/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://groundwork.timmo.dev/openapi.json.
- [MCP server](https://groundwork.timmo.dev/mcp): Streamable HTTP Model Context Protocol server with search_docs, get_page, list_pages, and get_navigation tools, plus every page as a resource. Discovery document: https://groundwork.timmo.dev/.well-known/mcp.json
- [Agent skills](https://groundwork.timmo.dev/.well-known/agent-skills/index.json): Agent Skills discovery index of the skills this site publishes.
- [API catalog](https://groundwork.timmo.dev/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here.
- [AI catalog](https://groundwork.timmo.dev/.well-known/ai-catalog.json): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs).
- [agent-readability.json](https://groundwork.timmo.dev/agent-readability.json): Manifest of every agent-facing artifact on this site.
- [Sitemap](https://groundwork.timmo.dev/sitemap.xml): Every indexable page URL with its last-modified date.