38 lines
2.5 KiB
Markdown
38 lines
2.5 KiB
Markdown
|
# Cloudflare Kumo UI Usage
|
||
|
|
|
||
|
|
Agent-facing guidance for the OpenDesign curated integration of Cloudflare Kumo UI.
|
||
|
|
|
||
|
|
## Read Order
|
||
|
|
|
||
|
|
1. Read this file for the package contract and source boundary.
|
||
|
|
2. Read `DESIGN.md` for Kumo's visual intent, semantic roles, component patterns, and accessibility guidance.
|
||
|
|
3. Paste the complete `tokens.css` into the first artifact `<style>` block before writing component CSS.
|
||
|
|
4. Read `components.manifest.json` for the compact inventory, then inspect `components.html` when selectors or interaction states matter.
|
||
|
|
5. Use the `preview/` pages for quick color, typography, spacing, and radius checks.
|
||
|
|
6. Consult `source/evidence.md` before making an upstream-fidelity claim.
|
||
|
|
|
||
|
|
## Design Highlights
|
||
|
|
|
||
|
|
- Use semantic surface roles to move from a near-white canvas through base, recessed, and elevated layers.
|
||
|
|
- Keep product text compact: `14px` is the default content size, with sentence-case headings and restrained semibold emphasis.
|
||
|
|
- Use the blue semantic brand background for primary actions; do not replace it with Cloudflare orange.
|
||
|
|
- Prefer line rings and small shadows to decorative gradients or heavy elevation.
|
||
|
|
- Use Kumo's native `data-mode="dark"` hook; `data-theme="dark"` is included only for OpenDesign artifact compatibility.
|
||
|
|
- Treat the section, container, and extended heading tokens as OpenDesign compatibility bindings, not upstream Kumo tokens.
|
||
|
|
|
||
|
|
## Do
|
||
|
|
|
||
|
|
- Choose tokens by semantic role and keep raw colors inside the canonical token block.
|
||
|
|
- Default ordinary actions to secondary buttons and reserve the primary treatment for the main decision.
|
||
|
|
- Preserve visible labels, native semantics, keyboard behavior, focus-visible rings, and non-color status cues.
|
||
|
|
- Reuse the fixture's buttons, fields, status badge, layer card, and data layout before introducing a new pattern.
|
||
|
|
- Keep loading controls disabled and labeled, and preserve layout dimensions while content loads.
|
||
|
|
- Respect reduced-motion preferences and keep information available without animation.
|
||
|
|
|
||
|
|
## Avoid
|
||
|
|
|
||
|
|
- Avoid presenting this package as official, endorsed, or maintained by Cloudflare.
|
||
|
|
- Avoid raw Tailwind palette colors, manual `dark:` variants, uppercase headings, altered tracking, or default `700` weight.
|
||
|
|
- Avoid nested LayerCards, placeholder-only field labels, unlabeled icon buttons, or color-only status communication.
|
||
|
|
- Avoid long hover transitions; Kumo color changes are immediate and larger state motion stays brief.
|
||
|
|
- Avoid editing `components.manifest.json` by hand; it is derived from `components.html` and `tokens.css`.
|