# xtyle

> xtyle is a themable-derivation engine and component contract. A named, swappable algorithm maps a small set of overridable anchors plus a few knobs into a full, internally-consistent design-token set, co-designed against a component library so any valid theme renders well out of the box. The algorithm is the durable asset; a theme is a materialized invocation of one.

xtyle separates the reusable engine (an **algorithm**) from any one materialized **theme**. The token register is open: authors declare new tokens and rewire derivation, held by a single hard contract, a coverage check between what components consume and what an algorithm produces. A derived theme is just CSS custom properties; the runtime is optional.

## Guides

- [Getting Started](https://xtyle.dev/start/): Derive a theme and build against the component contract in a few minutes.
- [Authoring Algorithms](https://xtyle.dev/algorithms/): Write an algorithm as an xript plugin: the mod anatomy, declared knobs, and the gauntlet that proves it.
- [Extending Components](https://xtyle.dev/extending-components/): Extend a custom element, subclass a shipped component, and satisfy the coverage rule for tokens you add.
- [Effects](https://xtyle.dev/effects/): The effect layer: `data-fx` spec strings (glow, throb, glare, lift, tint, frost, reveal, shake, saturate) applied under conditions, deriving intensity from the algorithm and honoring reduced motion.
- [MCP Server](https://xtyle.dev/mcp/): Run `xtyle mcp` to hand an agent the engine over stdio: derive, coverage, components, and gauntlet tools, plus docs and manifests as resources.
- [The Bench](https://xtyle.dev/generator/): Derive themes live in the browser and author algorithms on-site, theme and algorithm studio in one.
- [Changelog](https://xtyle.dev/changelog/): What changed in each xtyle release.

## Components

### Content

- [BBCode](https://xtyle.dev/components/bbcode/): Renders BBCode as themed HTML over a named, extensible tag vocabulary — as a document or an inline label.
- [Code](https://xtyle.dev/components/code/): A read-only, syntax-highlighted code block themed entirely from the code-token family.
- [Eyebrow](https://xtyle.dev/components/eyebrow/): The small uppercase kicker that sits above a heading.
- [Heading](https://xtyle.dev/components/heading/): A semantic section heading whose visual size is decoupled from its document level.
- [Kbd](https://xtyle.dev/components/kbd/): A keycap for the keys in a shortcut.
- [List](https://xtyle.dev/components/list/): A navigable, optionally-selectable collection of items — the reference skin over the shared collection substrate.
- [Markdown](https://xtyle.dev/components/markdown/): Renders markdown as themed HTML, as a document or as an inline label, with an optional source view.
- [Redact](https://xtyle.dev/components/redact/): Obscure a piece of content until it is revealed: blur it, block it, or mask it, and bring it back on hover, on a click, while held, or with a page-wide switch.
- [Table](https://xtyle.dev/components/table/): A styled data table around native `<table>`: zebra, bordered, hover, sticky header, and a sortable-header affordance.
- [Text](https://xtyle.dev/components/text/): A body-text primitive: paragraph or inline span across four sizes, four weights, three leadings, and four tones.
- [Theme Card](https://xtyle.dev/components/theme-card/): A preview of a theme, drawn as a small fake of a themed UI.
- [Theme Swatch](https://xtyle.dev/components/theme-swatch/): A theme's palette as a row of chips, read straight off the derivation.
- [Timeline](https://xtyle.dev/components/timeline/): A vertical activity feed: an ordered list drawn as a connected rail of dots.

### Controls

- [Button](https://xtyle.dev/components/button/): A clickable action: five variants across six semantic tones.
- [Checkbox](https://xtyle.dev/components/checkbox/): A styled native checkbox: checked, indeterminate, and disabled states.
- [Radio](https://xtyle.dev/components/radio/): A single-choice input: a styled native radio plus a group that manages roving focus and arrow-key navigation.
- [Rating](https://xtyle.dev/components/rating/): A rating control — interactive or read-only — that scores with any icon and shows fractional values as a partial icon.
- [Scheme Toggle](https://xtyle.dev/components/scheme-toggle/): A sun/moon control that flips the active light/dark scheme.
- [Segmented](https://xtyle.dev/components/segmented/): A single-select toggle bar: pick one of a few options from a connected button group.
- [Slider](https://xtyle.dev/components/slider/): A draggable range control for choosing a single value between a min and max, with full keyboard support.
- [Split Button](https://xtyle.dev/components/split-button/): A primary action with its variations behind a caret: one press for the thing you meant, a menu for the things you nearly meant.
- [Swatch](https://xtyle.dev/components/swatch/): A color chip pairing a colored dot with an optional label and value.
- [Switch](https://xtyle.dev/components/switch/): An on/off toggle that applies immediately, with an accessible name and optional state labels.

### Forms

- [Calendar](https://xtyle.dev/components/calendar/): A month grid that selects a day, a set of days, or a range — locale-aware, keyboard-complete, and popup-free.
- [Color Picker](https://xtyle.dev/components/color-picker/): An inline HSV color picker: a saturation/brightness field, a hue track with an opt-in alpha track, optional per-channel sliders for any model, and a switchable multi-format value field.
- [Combobox](https://xtyle.dev/components/combobox/): A text input that filters a themable listbox — autocomplete, single- or multi-select, with chips.
- [Date Picker](https://xtyle.dev/components/date-picker/): A typable date and time field with a calendar and clock popup, parsed against the locale.
- [Dropzone](https://xtyle.dev/components/dropzone/): A file drop target with a programmatic ingress a native host can drive, validation, a rejection surface, paste-to-upload, and a per-file upload list.
- [Field](https://xtyle.dev/components/field/): A labelled text input with helper text, validation, adornments, and built-in clear and reveal actions.
- [Form Group](https://xtyle.dev/components/form-group/): A label / description / error scaffold that wraps any slotted control and wires the accessibility plumbing.
- [Number Input](https://xtyle.dev/components/number-input/): A numeric field with stepper buttons, bounds, and step snapping, driven by pointer or keyboard.
- [Select](https://xtyle.dev/components/select/): A styled native dropdown: `.xtyle-control` chrome, a custom chevron, and a label, with valid and invalid states across three sizes.
- [Textarea](https://xtyle.dev/components/textarea/): A multi-line text input: styled, labelled, and resizable, in three sizes with an invalid state.
- [Theme Picker](https://xtyle.dev/components/theme-picker/): A gallery of themes to choose from, each previewed as it will look.

### Navigation

- [Bottom Nav](https://xtyle.dev/components/bottom-nav/): A thumb-reachable bottom tab bar: a real tablist with roving focus and an accent indicator.
- [Breadcrumb](https://xtyle.dev/components/breadcrumb/): A hierarchy trail showing where a page sits, with linked ancestors and a marked current location.
- [Link](https://xtyle.dev/components/link/): A text hyperlink: the anchor primitive, in three emphasis variants with an automatic external-link affordance.
- [Pagination](https://xtyle.dev/components/pagination/): A page navigator: previous/next controls around a windowed list of page numbers with ellipses.
- [Steps](https://xtyle.dev/components/steps/): A horizontal step indicator for a linear flow: done, current, and upcoming at a glance.
- [Tabs](https://xtyle.dev/components/tabs/): Sectioned content switching with a full WAI-ARIA tablist: three visual treatments, keyboard-driven.
- [Toc](https://xtyle.dev/components/toc/): An on-this-page table of contents that highlights the section currently in view.
- [Tree](https://xtyle.dev/components/tree/): A hierarchical, keyboard-navigable list of expandable nodes built from a data array.

### Feedback

- [Alert](https://xtyle.dev/components/alert/): An inline message banner with an optional severity glyph, a title, actions, and a dismissible form; color and meaning on independent axes.
- [Badge](https://xtyle.dev/components/badge/): A compact label, tag, or status chip: three fills across six semantic tones and twelve named hues, optionally removable.
- [Dot](https://xtyle.dev/components/dot/): A standalone status dot: a bare indicator in any tone, with optional ping, glow, and pulse.
- [Empty](https://xtyle.dev/components/empty/): A centered placeholder for a no-data state: an icon, a message, and an action.
- [Progress](https://xtyle.dev/components/progress/): A progress bar or capacity meter: a linear bar or circular ring with value thresholds that recolor and pulse.
- [Ribbon](https://xtyle.dev/components/ribbon/): A corner ribbon: a diagonal banner pinned to a container's corner for a short label, in any tone.
- [Skeleton](https://xtyle.dev/components/skeleton/): A shimmering loading placeholder in four shapes: text, line, block, and circle.
- [Spinner](https://xtyle.dev/components/spinner/): An indeterminate loading indicator: a spinning ring in any of the six semantic tones, in three sizes.
- [Toast](https://xtyle.dev/components/toast/): A transient notification that announces itself and slips away; color and meaning on independent axes, in a live-region stack.

### Overlays

- [Command Palette](https://xtyle.dev/components/command-palette/): A modal, filterable, keyboard-first index of everything an app can do.
- [Dialog](https://xtyle.dev/components/dialog/): A centered modal built on the native `<dialog>` element: scrim, focus trap, and Esc-to-close come for free.
- [Menu](https://xtyle.dev/components/menu/): A menu button, or a cursor-anchored context menu: a popup list of actions.
- [Popover](https://xtyle.dev/components/popover/): The generic anchored surface: a floating panel tethered to a trigger, an element, or a point.
- [Sheet](https://xtyle.dev/components/sheet/): An edge-anchored overlay built on the native `<dialog>`: a drawer that slides in from any of the four sides, safe-area aware and swipe-dismissible.
- [Spotlight](https://xtyle.dev/components/spotlight/): Isolate one thing and say something about it: the page dims and blurs, a hole is cut over the target, and a callout points at it.
- [Tooltip](https://xtyle.dev/components/tooltip/): A hover/focus hint that floats a short description beside its trigger, on any of four sides.
- [Tour](https://xtyle.dev/components/tour/): A guided sequence of Spotlights: point at one thing, say something, and move to the next with Back / Next / Skip and a progress readout.

### Media

- [Avatar](https://xtyle.dev/components/avatar/): An identity chip: a photo when one loads, a tinted initials-or-icon fallback when it doesn't.
- [Avatar Group](https://xtyle.dev/components/avatar-group/): A row of overlapping avatars with a trailing `+N` overflow chip, for a contributor, attendee, or reviewer stack.
- [Carousel](https://xtyle.dev/components/carousel/): A scroll-snap track of slides with prev/next controls, dots, keyboard, and opt-in autoplay.
- [Hero](https://xtyle.dev/components/hero/): A top-of-page band that composes an eyebrow, heading, text, actions, and media into a hero.
- [Icon](https://xtyle.dev/components/icon/): A functional glyph, or a mark generated from a name, drawn in the current text color.
- [Image](https://xtyle.dev/components/image/): A responsive image in an aspect-ratio frame, with a loading shimmer and an opt-in lightbox.
- [Nine Patch](https://xtyle.dev/components/nine-patch/): Artwork sliced into a frame that scales without smearing its corners.
- [Parallax](https://xtyle.dev/components/parallax/): A layered banner whose layers drift on scroll or follow the cursor, static with no JS or reduced motion.
- [QR Code](https://xtyle.dev/components/qr/): A themeable QR code that derives its colors from the active theme, drops an icon in the middle, and can fall back to guaranteed-scannable black-on-white.

### Metrics

- [Bar](https://xtyle.dev/components/bar/): A grouped or stacked bar chart, colored from a theme-derived series palette, with an interactive value readout and opt-in clickable bars.
- [Chart](https://xtyle.dev/components/chart/): A multi-series line or area chart with real x and y axes, a time or numeric domain, and a cursor that reads every series at once.
- [Heatmap](https://xtyle.dev/components/heatmap/): A 2D intensity grid (the activity-calendar / punch-card shape), colored on a theme-derived ramp, with a per-cell readout and opt-in clickable cells.
- [Pie](https://xtyle.dev/components/pie/): A pie or donut chart of parts against a whole, colored from a theme-derived palette, with an interactive readout.
- [Sparkline](https://xtyle.dev/components/sparkline/): A tiny, word-sized trend line, area, bar, or occupancy chart, single-tone and axis-free, for inline use or a live time-series.
- [Stat](https://xtyle.dev/components/stat/): A single metric: a prominent value with its label, optional trend delta, and caption.

### Layout

- [Accordion](https://xtyle.dev/components/accordion/): A stack of collapsible sections, one or many open at a time, driven by pointer or keyboard.
- [Card](https://xtyle.dev/components/card/): A surface container that groups related content, with optional header and footer regions.
- [Card Link](https://xtyle.dev/components/card-link/): A whole card that is a single link: the click target is the card, not a button inside it.
- [Cluster](https://xtyle.dev/components/cluster/): A horizontal flex row that wraps, for toolbars, tag lists, and inline action groups.
- [Grid](https://xtyle.dev/components/grid/): A two-dimensional CSS grid: fixed columns, responsive auto-fit, or a content-plus-rail shell.
- [Panel](https://xtyle.dev/components/panel/): A titled content region: a header with a configurable heading and actions, a body, an optional footer, and an optional collapsible or scrollable form.
- [Reveal](https://xtyle.dev/components/reveal/): A lid that slides aside to expose a belly of detail or actions underneath.
- [Section](https://xtyle.dev/components/section/): A page band or a framed stage: the full-width strips and demo grounds a page is built from.
- [Separator](https://xtyle.dev/components/separator/): A hairline divider: horizontal or vertical, optionally with a centered label, in two weights.
- [Stack](https://xtyle.dev/components/stack/): A vertical flex column with a token-driven gap, the primitive for stacking content.
- [Theme Scope](https://xtyle.dev/components/theme-scope/): A provider that derives an invocation and themes everything inside it.

### Shell

- [App Shell](https://xtyle.dev/components/app-shell/): The three-row application scaffold: toolbar over a left/main/right body over a status bar.
- [Dock](https://xtyle.dev/components/dock/): The side rail: a vertical panel pinned to the left or right edge of the shell.
- [Dock Zone](https://xtyle.dev/components/dock-zone/): A drag-and-drop dockable-panel workspace: tabbed zones that rearrange by dragging.
- [Mobile Shell](https://xtyle.dev/components/mobile-shell/): The touch-app frame: a sticky app bar, one scrolling column, and a bottom nav in thumb reach.
- [Splitter](https://xtyle.dev/components/splitter/): A draggable divider that resizes an adjacent pane, with configurable bounds and steps.
- [Statusbar](https://xtyle.dev/components/statusbar/): The footer status strip: a compact, monospace row of status items separated by flexible spacers.
- [Toolbar](https://xtyle.dev/components/toolbar/): The header bar: a title plus structured start, center, and end regions for actions and navigation.

## Full text

- [Full documentation](https://xtyle.dev/llms-full.txt): every concept and component reference inlined.