# Designing with XWUI - the AI-readable guide This page tells an AI assistant (or a fast-moving human) how to build a correct XWUI interface. XWUI is 1,300+ framework-agnostic Web Components with a typed, validatable contract per component. You do not guess prop names here: you fetch the schema, write config as data, validate, then render. ## The 60-second mental model 1. Every component is a custom element (``) AND a class (`new XWUIButton(container, data, conf?)`). Same contract both ways. 2. Config is data, split in two: `data` (content: text, rows, items) and `conf_comp` (appearance/behavior: variant, size, shape). 3. Every component has a draft-07 JSON Schema describing both buckets with enums and defaults. The schema is the API. 4. Theming is HTML attributes on `` driven by design tokens: `data-theme` (light/dark), `data-accent`, `data-style`, `data-roundness`, `data-brand`, `data-font`. Never restyle components by CSS overrides first; switch tokens. 5. Tiers: `basic` (incl. `input`) is free and loads from the CDN; `dashboard`, `power`, `chart`, `super`, `game`, `gis`, `industry` are licensed and ship sealed. Free quick starts use basic-tier elements only. ## The loop your agent should run ```text search/list -> get schema -> draft config -> VALIDATE -> render ``` Live MCP endpoint (all of the above as tools): ```json { "mcpServers": { "xwui": { "type": "http", "url": "https://xwui.dev/mcp" } } } ``` Tools: `list_components`, `search_components`, `get_component_schema`, `get_component_example`, `validate_component_config`, `suggest_import`, `list_presets`, `get_llms_txt`. `validate_component_config` returns precise issues ("conf.variant must be one of [...]") BEFORE anything renders. Without MCP, the same contract is static: | Artifact | URL | |----------|-----| | Concise reference | https://xwui.dev/llms.txt | | Complete reference | https://xwui.dev/llms-full.txt | | Custom Elements Manifest (typed attributes) | https://xwui.dev/custom-elements.json | | Component index (name, tag, tier, path) | https://xwui.dev/__component_index__.json | | Per-component JSON Schemas | https://xwui.dev/schemas/v1/index.json | | Site-from-JSON DSL schema | https://xwui.dev/schemas/v1/xwweb.config.schema.json | ## Render paths ```html ``` ```js // 2. Imperative: config-as-data, same schema. const XWUITable = await XWUI.get('XWUITable'); new XWUITable(document.querySelector('#out'), { columns: ['Name', 'Email'], rows: [] }, // data { size: 'compact' }); // conf_comp ``` ```json // 3. Whole site from one JSON document (the xwweb DSL): { "$schema": "https://xwui.dev/schemas/v1/xwweb.config.schema.json", "mountId": "app", "pages": [ { "path": "/", "title": "Home", "nav": "primary", "blocks": [ { "mode": "markdown", "content": "# Hello" } ] } ] } ``` ## Rules that prevent the classic mistakes - Do not `npm install @exonware/xwui` today: the package is not yet published. Use the CDN loader or an import map to `https://xwui.dev/esm/basic.bundle.js`. - Do not showcase sealed-tier components (spreadsheet, charts, kanban) in a free-tier context; they will not load without a licence. - Complex values pass as JSON strings in attributes (`rows='[{"name":"A"}]'`) or as real objects via the class/property path. - Validate before render. The schema knows more than your training data.