Agents
How to wire this library up to a coding agent: where llms.txt lives, the import surface, and the house rules that keep generated code correct.
Point the agent at llms.txt
Every page on this site is indexed in a single machine-readable file, following the llms.txt convention. There is one line per page, with its URL and a one-sentence description of what it covers.
https://design.hyzer.sh/llms.txtRead it here. It is generated from the same manifest that builds this site's navigation, so it cannot fall out of date with the docs it points at.
The index is one line per page. For an agent that would rather fetch once than crawl, there is a companion file with the whole component reference in it: every component's props, styling hooks, and accessibility notes, in one document.
https://design.hyzer.sh/llms-full.txtRead llms-full.txt here. The same reference is also available as JSON, built from the same walk, for an agent that wants to look a single component up by name rather than read the whole file.
https://design.hyzer.sh/llms-full.jsonWhere each import comes from
Components come from the package root. Everything else lives behind a named subpath, so an agent never has to guess whether something is a component, a utility, or a type.
import { Button, Modal, Combobox } from '@hyzer-labs/ui'; // components
import { defineConfig } from '@hyzer-labs/ui/config'; // token engine
import { reveal, fade } from '@hyzer-labs/ui/motion'; // motion
import { intersect } from '@hyzer-labs/ui/observers'; // observers
import IconSearch from '@hyzer-labs/ui/icons/search'; // one glyph at a time
import { contrastRatio } from '@hyzer-labs/ui/utils'; // utilities
import type { Intent } from '@hyzer-labs/ui/types'; // types
import '@hyzer-labs/ui/tokens.css'; // required
import '@hyzer-labs/ui/theme'; // optional reference theme
import '@hyzer-labs/ui/reset.css'; // optional structural resetHouse rules
These are the conventions that account for most of what generated code gets wrong with this library. They are also the contents of the AGENTS.md file below, so a rule stated here and a rule handed to an agent cannot drift apart.
Prefer the library components over hand-rolling your own
If a component exists, compose it. Hand-rolled markup re-solves problems the library already solved, and it will not pick up theme changes, token overrides or accessibility fixes. Extend what is here instead: snippets when you need different structure, the class prop and the documented hooks when you need a different look.
Meet WCAG AA, and use the accessibility already here
AA is the floor, not the goal. Components ship the ARIA roles, keyboard handling and focus management of their WAI-ARIA pattern, so use them rather than rebuilding the pattern. Bad ARIA is worse than no ARIA: adding role, tabindex or key handlers on top of a component usually breaks behavior that already worked. If a component looks like it is missing an accessible name, look for a label prop first.
Generate tokens; never hand-edit them
The token sheet is build output. Change hyzer.config.ts and run hyzer generate. A hand edit is overwritten on the next run, and it skips the contrast grading that would have caught an inaccessible pairing.
Resolve through roles and intents, never the palette
In component CSS, use --hz-color-* for structural roles such as surface, text and border, and --hz-intent-* for meaning such as danger or success. --hz-palette-* is the raw hue layer those resolve through. Read it directly and you skip the layer a consumer themes: someone who repoints --hz-color-border, or remaps --hz-intent-danger to a different hue, sees no effect on your component.
Apply named themes with data-theme
Define each theme under themes in the config, then apply one with a data-theme attribute or the theme attachment. It works on <html> or on any element, which is how a single section carries its own theme. Dark is one named theme, not a special mode.
export default defineConfig({
themes: {
dark: { palette: { primary: '#60a5fa' } },
ocean: { palette: { primary: '#0ea5e9' } }
}
});Restyle through the class prop
Every component accepts class and merges it onto its root, so a single instance can be restyled without a wrapper element and without !important.
<!-- Yes -->
<Button class="checkout-cta">Place order</Button>
<!-- Not this: a wrapper element just to reach the component -->
<div class="checkout-cta"><Button>Place order</Button></div>Drop this in your repo
The rules above, as a file. It is generated from the same source as this page, so it never falls behind what you just read.
AGENTS.md in your project root, where coding agents look for project instructions.# @hyzer-labs/ui — conventions for coding agents
The conventions that keep generated code correct against @hyzer-labs/ui, a
headless Svelte 5 component library.
Full documentation: https://design.hyzer.sh/docs
Machine-readable index of every page: https://design.hyzer.sh/llms.txt
Every component's props and styling hooks in one file: https://design.hyzer.sh/llms-full.txt
The same reference as JSON, for keyed lookup: https://design.hyzer.sh/llms-full.json
## Imports
Components come from the package root. Everything else lives behind a named
subpath, so there is never a guess about whether something is a component, a
utility, or a type.
```ts
import { Button, Modal, Combobox } from '@hyzer-labs/ui'; // components
import { defineConfig } from '@hyzer-labs/ui/config'; // token engine
import { reveal, fade } from '@hyzer-labs/ui/motion'; // motion
import { intersect } from '@hyzer-labs/ui/observers'; // observers
import IconSearch from '@hyzer-labs/ui/icons/search'; // one glyph at a time
import { contrastRatio } from '@hyzer-labs/ui/utils'; // utilities
import type { Intent } from '@hyzer-labs/ui/types'; // types
import '@hyzer-labs/ui/tokens.css'; // required
import '@hyzer-labs/ui/theme'; // optional reference theme
import '@hyzer-labs/ui/reset.css'; // optional structural reset
```
## House rules
### Prefer the library components over hand-rolling your own
If a component exists, compose it. Hand-rolled markup re-solves problems the library already solved, and it will not pick up theme changes, token overrides or accessibility fixes. Extend what is here instead: snippets when you need different structure, the `class` prop and the documented hooks when you need a different look.
### Meet WCAG AA, and use the accessibility already here
AA is the floor, not the goal. Components ship the ARIA roles, keyboard handling and focus management of their WAI-ARIA pattern, so use them rather than rebuilding the pattern. Bad ARIA is worse than no ARIA: adding `role`, `tabindex` or key handlers on top of a component usually breaks behavior that already worked. If a component looks like it is missing an accessible name, look for a label prop first.
### Generate tokens; never hand-edit them
The token sheet is build output. Change `hyzer.config.ts` and run `hyzer generate`. A hand edit is overwritten on the next run, and it skips the contrast grading that would have caught an inaccessible pairing.
### Resolve through roles and intents, never the palette
In component CSS, use `--hz-color-*` for structural roles such as surface, text and border, and `--hz-intent-*` for meaning such as danger or success. `--hz-palette-*` is the raw hue layer those resolve through. Read it directly and you skip the layer a consumer themes: someone who repoints `--hz-color-border`, or remaps `--hz-intent-danger` to a different hue, sees no effect on your component.
### Apply named themes with data-theme
Define each theme under `themes` in the config, then apply one with a `data-theme` attribute or the `theme` attachment. It works on `<html>` or on any element, which is how a single section carries its own theme. Dark is one named theme, not a special mode.
```ts
export default defineConfig({
themes: {
dark: { palette: { primary: '#60a5fa' } },
ocean: { palette: { primary: '#0ea5e9' } }
}
});
```
### Restyle through the class prop
Every component accepts `class` and merges it onto its root, so a single instance can be restyled without a wrapper element and without `!important`.
```svelte
<!-- Yes -->
<Button class="checkout-cta">Place order</Button>
<!-- Not this: a wrapper element just to reach the component -->
<div class="checkout-cta"><Button>Place order</Button></div>
```
You can also fetch it directly: /agents.md.