uxonfly-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phanindhra Kondru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# UXonFly
+
+> An open-source design system for AI coding sessions.
+> Strong opinions. MIT licensed.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
+
+## What this is
+
+Every AI coding session starts blind. Generic shadcn components. Default
+Tailwind colors. Modal-inside-a-modal. Empty states with no CTA. Errors in
+toasts that should be inline. Destructive actions with single-click delete.
+
+UXonFly is a curated set of design and UX rules — tokens, components, UX
+patterns, flows, copy rules, and principles — that your AI reads before
+generating UI. The rules live in one markdown file: `uxonfly.md`.
+
+**Two ways to use it. Same content, same rules:**
+
+1. **As a file** — copy `uxonfly.md` into your project. Your AI reads it natively every session. Zero install.
+2. **As an MCP server** — run `uxonfly-mcp` and your AI invokes 7 tools (`get_component`, `get_ux_pattern`, …) on demand.
+
+The file install is the recommended starting point. The MCP server is the
+upgrade for power users who want tool-call precision.
+
+MIT licensed. Fork it. Improve it. Send a PR.
+
+## What's in it
+
+- **5 token categories** — colors, typography, spacing, shape, shadows
+- **6 components** — button, input, card, badge, modal, toast
+- **9 UX patterns** — navigation, modals, forms, loading, empty states, errors, destructive actions, data tables, notifications
+- **3 flows** — empty-state, onboarding, auth
+- **Copy rules** — voice, tense, errors, CTAs, tooltips, placeholders, labels
+- **7 principles** — accessibility first, one primary action, error prevention, progressive disclosure, copy-driven, keyboard navigable, trust the system
+
+Strong opinions. Border-first. Modern SaaS aesthetic (Linear / Stripe / Vercel-aligned).
+
+---
+
+## Install option 1 — file (recommended, 30 seconds)
+
+This is the only step you need.
+
+```bash
+# Download the rulebook
+curl -O https://raw.githubusercontent.com/Phanikondru/uxonfly-mcp/main/uxonfly.md
+
+# For Claude Code:
+mv uxonfly.md CLAUDE.md
+
+# OR for Cursor:
+mv uxonfly.md .cursorrules
+```
+
+Open your AI tool and start prompting. It will read the file before generating
+UI on every session.
+
+That's it. No npm install. No config. No login.
+
+---
+
+## Install option 2 — MCP server (power users)
+
+If you want your AI to invoke specific tools (`get_component`,
+`get_ux_pattern`, `get_tokens`, …) on demand instead of reading the whole
+file every prompt, run UXonFly as a local MCP server.
+
+> **Status**: `uxonfly-mcp` is not yet published to npm. The one-line `npx`
+> install will work after the first publish — until then, use the local-build
+> path below.
+
+### Install today (local build)
+
+```bash
+git clone https://github.com/Phanikondru/uxonfly-mcp.git
+cd uxonfly-mcp
+npm install
+npm run build
+```
+
+Then point your AI tool at the compiled binary using its absolute path.
+
+**Claude Code:**
+
+```bash
+claude mcp add uxonfly -- node /absolute/path/to/uxonfly-mcp/build/index.js
+```
+
+**Cursor** — add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "uxonfly": {
+      "command": "node",
+      "args": ["/absolute/path/to/uxonfly-mcp/build/index.js"]
+    }
+  }
+}
+```
+
+### After the first npm publish (coming soon)
+
+Once `uxonfly-mcp` is on the npm registry, the install collapses to one command.
+
+**Claude Code:**
+
+```bash
+claude mcp add uxonfly -- npx -y uxonfly-mcp
+```
+
+**Cursor** — `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "uxonfly": {
+      "command": "npx",
+      "args": ["-y", "uxonfly-mcp"]
+    }
+  }
+}
+```
+
+### Available tools
+
+| Tool | When AI calls it | Returns |
+| --- | --- | --- |
+| `get_design_system` | Before any UI task | Full system |
+| `get_component` | Before generating a component | Component spec |
+| `get_tokens` | Before writing CSS / Tailwind | Tokens |
+| `get_ux_pattern` | Before any UX decision | Pattern |
+| `get_flow` | Before any multi-step flow | Flow spec |
+| `get_copy_rules` | Before writing interface copy | Copy rules |
+| `get_rules` | Before layout / IA decisions | Principles |
+
+Each tool description begins with `ALWAYS call…` so your AI invokes them
+proactively before generating UI code (the trick: the tool description
+itself is the instruction).
+
+### Custom rulebook
+
+Point the MCP server at your own version of `uxonfly.md` via the
+`UXONFLY_MD_PATH` environment variable:
+
+```bash
+# Local build (works today):
+UXONFLY_MD_PATH=/absolute/path/to/your/uxonfly.md \
+  node /absolute/path/to/uxonfly-mcp/build/index.js
+
+# After npm publish:
+UXONFLY_MD_PATH=/absolute/path/to/your/uxonfly.md npx uxonfly-mcp
+```
+
+---
+
+## Local development
+
+```bash
+git clone https://github.com/Phanikondru/uxonfly-mcp.git
+cd uxonfly-mcp
+npm install
+npm run dev    # run with tsx
+npm run build  # compile to ./build
+npm start      # run the compiled server
+```
+
+---
+
+## Contributing
+
+The whole point of this project: one designer's opinions become a shared
+standard the community keeps improving. PRs welcome.
+
+How to help:
+
+- Open an issue if you think a rule is wrong, missing, or unclear
+- Send a PR for new components, patterns, or principles you've battle-tested
+- Add real-world usage examples (apps you've built with `uxonfly.md`)
+
+Goal: make UXonFly *better* than any one designer's taste alone.
+
+---
+
+## About
+
+Built by [phanikondru](https://x.com/Phanikondru) — designer with 4 years
+of production UX experience, building in public.
+
+Just trying to build good things. **Design + AI + Code.**
+
+UXonFly was built with Gemini, Cursor, and the rules in `uxonfly.md`
+itself — the same system that ships with this package. The tool eats its
+own dog food.
+
+Follow the project: [@Phanikondru](https://x.com/Phanikondru)
+
+---
+
+## License
+
+MIT. Use it commercially. Fork it. Modify it. Just keep the LICENSE file.

package/build/index.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * uxonfly-mcp — Designer intelligence for every AI coding session.
+ *
+ * A Model Context Protocol server exposing the UXonFly design system,
+ * UX patterns, and product principles to any MCP-compatible AI tool
+ * (Cursor, Claude Code, Windsurf, VS Code, Zed).
+ *
+ * Each tool description begins with "ALWAYS call..." so the AI invokes
+ * them proactively before writing UI code — the tool description is the
+ * instruction (see PRD §4.3).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+// ─── Load the base system ────────────────────────────────────────────
+const DEFAULT_MD_PATH = resolve(dirname(fileURLToPath(import.meta.url)), "..", "uxonfly.md");
+function loadSystem() {
+    const path = process.env.UXONFLY_MD_PATH ?? DEFAULT_MD_PATH;
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (err) {
+        console.error(`[uxonfly-mcp] failed to read ${path}:`, err);
+        process.exit(1);
+    }
+}
+const SYSTEM = loadSystem();
+// ─── Markdown section slicing ────────────────────────────────────────
+// Extracts content under a heading until the next heading of equal or
+// shallower depth. Keeps the MCP server dependency-free (no markdown lib).
+function getSection(md, heading, level = 2) {
+    const marker = "#".repeat(level) + " ";
+    const lines = md.split("\n");
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === (marker + heading).trim()) {
+            start = i + 1;
+            break;
+        }
+    }
+    if (start === -1)
+        return null;
+    let end = lines.length;
+    for (let i = start; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line.startsWith("#")) {
+            const depth = line.match(/^#+/)?.[0].length ?? 0;
+            if (depth <= level) {
+                end = i;
+                break;
+            }
+        }
+    }
+    return lines.slice(start, end).join("\n").trim();
+}
+const asText = (text) => ({
+    content: [{ type: "text", text }],
+});
+const notFound = (what) => asText(`[uxonfly] not found: ${what}. Check uxonfly.md for available sections.`);
+// ─── Server ──────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "uxonfly-mcp",
+    version: "0.1.0",
+});
+// Tool 1 — complete design system
+server.registerTool("get_design_system", {
+    title: "Get UXonFly Design System",
+    description: "ALWAYS call this tool before writing any UI code. Returns the complete 3-layer UXonFly design system for this project: visual language (tokens, components, layout), UX patterns (navigation, modals, forms, loading, empty states, errors, destructive actions, tables, notifications), and product principles. Do not invent design decisions — follow what this tool returns.",
+    inputSchema: {},
+}, async () => asText(SYSTEM));
+// Tool 2 — specific component
+server.registerTool("get_component", {
+    title: "Get Component Spec",
+    description: "ALWAYS call this before generating any UI component (button, input, card, badge, modal, toast, etc.). Returns the full component spec: sizes, variants, states, and UX rules. Never improvise component specs.",
+    inputSchema: {
+        name: z
+            .string()
+            .describe("Component name, lowercase. E.g. 'button', 'input', 'card', 'badge', 'modal', 'toast'."),
+    },
+}, async ({ name }) => {
+    const components = getSection(SYSTEM, "Components", 2);
+    if (!components)
+        return notFound("Components section");
+    const spec = getSection(components, name.toLowerCase(), 3);
+    return spec ? asText(spec) : notFound(`component '${name}'`);
+});
+// Tool 3 — design tokens
+server.registerTool("get_tokens", {
+    title: "Get Design Tokens",
+    description: "ALWAYS call this before writing CSS, Tailwind config, CSS variables, or any styling code. Returns the complete token set: colors (with all semantic variants), typography scale, spacing scale, border radius, and shadows. Never use values outside these tokens.",
+    inputSchema: {},
+}, async () => {
+    const tokens = getSection(SYSTEM, "Tokens", 2);
+    return tokens ? asText(tokens) : notFound("Tokens section");
+});
+// Tool 4 — UX pattern for a context
+server.registerTool("get_ux_pattern", {
+    title: "Get UX Pattern",
+    description: "ALWAYS call this before making any UX decision. Covers destructive actions, forms, modals, loading states, empty states, errors, navigation, data tables, and notifications. Returns the correct pattern plus implementation guidance. Never guess at UX decisions.",
+    inputSchema: {
+        context: z
+            .string()
+            .describe("UX context. E.g. 'destructive-actions', 'forms', 'empty-states', 'errors', 'loading', 'modals', 'navigation', 'data-tables', 'notifications'."),
+    },
+}, async ({ context }) => {
+    const patterns = getSection(SYSTEM, "UX Patterns", 2);
+    if (!patterns)
+        return notFound("UX Patterns section");
+    const match = getSection(patterns, context.toLowerCase(), 3);
+    return match ? asText(match) : notFound(`pattern '${context}'`);
+});
+// Tool 5 — multi-step flow
+server.registerTool("get_flow", {
+    title: "Get UX Flow",
+    description: "ALWAYS call this before building any multi-step flow. Returns a complete flow spec: all screens, states, transitions, success and error handling. Never design flows from scratch.",
+    inputSchema: {
+        flow_name: z
+            .string()
+            .describe("Flow name. E.g. 'empty-state', 'onboarding', 'auth'."),
+    },
+}, async ({ flow_name }) => {
+    const flows = getSection(SYSTEM, "Flows", 2);
+    if (!flows)
+        return notFound("Flows section");
+    const flow = getSection(flows, flow_name.toLowerCase(), 3);
+    return flow ? asText(flow) : notFound(`flow '${flow_name}'`);
+});
+// Tool 6 — copy rules
+server.registerTool("get_copy_rules", {
+    title: "Get Copy Rules",
+    description: "ALWAYS call this before writing any interface copy — error messages, CTAs, empty-state text, tooltips, placeholders, labels. Returns tone, voice, tense, and format rules. Never write copy without checking these.",
+    inputSchema: {},
+}, async () => {
+    const copy = getSection(SYSTEM, "Copy Rules", 2);
+    return copy ? asText(copy) : notFound("Copy Rules section");
+});
+// Tool 7 — product and design principles
+server.registerTool("get_rules", {
+    title: "Get Product Principles",
+    description: "ALWAYS call this before making layout or information architecture decisions. Returns all product and design principles for this project: progressive disclosure, primary-action rules, error prevention, copy-driven UI, keyboard navigation, and accessibility.",
+    inputSchema: {},
+}, async () => {
+    const rules = getSection(SYSTEM, "Principles", 2);
+    return rules ? asText(rules) : notFound("Principles section");
+});
+// ─── Start ───────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[uxonfly-mcp] running on stdio");
+}
+main().catch((err) => {
+    console.error("[uxonfly-mcp] fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "uxonfly-mcp",
+  "version": "0.1.0",
+  "description": "Designer intelligence for every AI coding session. Production-grade UX. On the fly.",
+  "type": "module",
+  "bin": {
+    "uxonfly-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "uxonfly.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "dev": "tsx src/index.ts",
+    "start": "node build/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "design-system",
+    "ux",
+    "ai",
+    "cursor",
+    "claude-code",
+    "windsurf",
+    "vibe-coding"
+  ],
+  "author": {
+    "name": "phanikondru",
+    "url": "https://x.com/Phanikondru"
+  },
+  "license": "MIT",
+  "homepage": "https://uxonfly.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Phanikondru/uxonfly-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Phanikondru/uxonfly-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/uxonfly.md

@@ -0,0 +1,651 @@
+# UXonFly — Design System
+
+> Production-grade design and UX rules for AI coding sessions.
+>
+> Drop this file in your project root as `CLAUDE.md` (Claude Code) or
+> `.cursorrules` (Cursor). Your AI will read it on every prompt and follow
+> these rules instead of generating generic UI.
+>
+> Strong opinions. Border-first. Modern SaaS aesthetic
+> (Linear / Stripe / Vercel-aligned). MIT licensed.
+> Improvements welcome via PRs at github.com/Phanikondru/uxonfly-mcp.
+
+---
+
+## Tokens
+
+### Colors
+
+Brand color: `#6366F1` (indigo). Replace with your own brand hex — every
+other color is derived from it.
+
+Semantic palette:
+
+- `--color-primary`: #6366F1
+- `--color-primary-hover`: #4F46E5
+- `--color-primary-active`: #4338CA
+- `--color-primary-subtle`: #EEF2FF
+- `--color-text`: #0F172A (slate-900 — never pure black)
+- `--color-text-muted`: #64748B (slate-500)
+- `--color-text-subtle`: #94A3B8 (slate-400)
+- `--color-surface`: #FFFFFF
+- `--color-surface-subtle`: #F8FAFC (slate-50)
+- `--color-surface-sunken`: #F1F5F9 (slate-100)
+- `--color-border`: #E2E8F0 (slate-200)
+- `--color-border-strong`: #CBD5E1 (slate-300)
+- `--color-success`: #10B981 (emerald-500)
+- `--color-warning`: #F59E0B (amber-500)
+- `--color-danger`: #EF4444 (red-500)
+- `--color-info`: #3B82F6 (blue-500)
+
+Rules:
+
+- Never use pure black (`#000`) for text. Use slate-900 (`#0F172A`).
+- Never use pure white surfaces against muted backgrounds. Use slate-50 for muted areas.
+- The primary brand color is for ONE primary action per screen. Don't decorate with it.
+- Semantic colors (success / warning / danger) appear only on status indicators — never as decoration.
+
+Dark mode: invert surface and text. Brand color stays the same hue.
+
+- `--color-surface` → `#0F172A` (slate-900)
+- `--color-surface-subtle` → `#1E293B` (slate-800)
+- `--color-text` → `#F8FAFC` (slate-50)
+- `--color-text-muted` → `#94A3B8` (slate-400)
+- `--color-border` → `#1E293B` (slate-800)
+
+### Typography
+
+- Display: **Cal Sans** (fallback: Inter Display)
+- Body: **Inter**
+- Mono: **JetBrains Mono**
+
+Type scale (px):
+
+- `xs`: 12 / 16 line-height
+- `sm`: 14 / 20
+- `base`: 16 / 24 (default body)
+- `lg`: 18 / 28
+- `xl`: 20 / 28
+- `2xl`: 24 / 32
+- `3xl`: 32 / 40
+- `4xl`: 48 / 52
+
+Weights:
+
+- 400 (regular) — body text
+- 500 (medium) — UI labels, buttons
+- 600 (semibold) — headings, emphasis
+- 700 (bold) — top-level page titles only, used sparingly
+
+Rules:
+
+- Body text is 16px minimum. Never smaller for readable content.
+- Line height: body 1.5, headings 1.2.
+- Never use more than 3 distinct font sizes on a single screen.
+
+### Spacing
+
+8-stop scale (pixels): `4 / 8 / 12 / 16 / 24 / 32 / 48 / 64`
+
+Rules:
+
+- Use only these values. No 7px, no 20px, no 50px.
+- Default gap between major sections: 32px.
+- Default gap between fields in a form: 16px.
+- Default page padding: 24px desktop, 16px mobile.
+- Compact UI (toolbars, dense tables): 8px gaps.
+
+### Shape
+
+Border radius scale:
+
+- `sm`: 4px (badges, small chips)
+- `md`: 8px (default — buttons, inputs)
+- `lg`: 12px (cards, modals)
+- `xl`: 16px (hero sections, large containers)
+- `full`: 9999px (avatars, pill buttons)
+
+Rules:
+
+- Default radius is `md` (8px). Use it unless there's a reason not to.
+- Never mix radius sizes inside the same component.
+- Never use square corners (radius 0) on interactive elements.
+
+### Shadows
+
+**Border-first philosophy**: separation comes from borders, not shadows.
+
+One shadow only — for genuinely elevated things:
+
+```
+shadow-elevated: 0 1px 3px rgba(15, 23, 42, 0.08), 0 1px 2px rgba(15, 23, 42, 0.06)
+```
+
+Use for:
+
+- Modals (backdrop creates the elevation, shadow makes it feel held)
+- Popovers and dropdowns
+- Toasts
+- Floating UI (FABs, command palettes)
+
+Never use for:
+
+- Cards in a list (use a border instead)
+- Buttons (use the primary color, not a shadow, to indicate elevation)
+- Inputs (use a focus ring, not a shadow)
+- Headers, sidebars, navigation (use a `border-bottom`)
+
+If you find yourself reaching for a shadow on a card, you want a border.
+
+---
+
+## Components
+
+### button
+
+Sizes:
+
+- `sm`: 32px height, 12px horizontal padding, 14px text
+- `md`: 40px height, 16px horizontal padding, 14px text (default)
+- `lg`: 48px height, 24px horizontal padding, 16px text
+
+Variants:
+
+- `primary` — brand color background, white text. ONE per screen, max.
+- `secondary` — surface background, border, text color. Default for everything that isn't the primary action.
+- `ghost` — transparent background, no border, text color. For tertiary actions in toolbars and inline contexts.
+- `danger` — red background, white text. For destructive actions only. Always paired with a 2-step confirmation.
+
+States (every variant):
+
+- `default` — base styling
+- `hover` — slightly darker background (use the `-hover` token)
+- `active` — even darker background (use the `-active` token)
+- `focus-visible` — 2px ring in primary color at 50% opacity, 2px offset
+- `disabled` — 50% opacity, `cursor: not-allowed`, no hover
+- `loading` — spinner replaces label, button width stays the same
+
+Rules:
+
+- Maximum ONE `primary` button per screen. If two actions are equally important, redesign the screen.
+- Destructive actions ALWAYS use the `danger` variant. Never red-color a primary button.
+- Loading state: spinner replaces the label text but the button width does not change.
+- Never use buttons for navigation. Navigation is for `<a>` tags. Buttons are for actions.
+- Icon-only buttons require an `aria-label`.
+
+### input
+
+Default size: 40px height, 12px horizontal padding, 14px text.
+Border: 1px solid `--color-border`, radius `md`.
+Focus: 2px ring in `--color-primary` at 50% opacity, 2px offset.
+
+Rules:
+
+- Label ALWAYS above the field, always visible. Never use placeholder-as-label.
+- Mark optional fields with `(optional)`. Never mark required fields with `*`.
+- Validation runs on `blur`, never on every keystroke (one exception: password strength meters).
+- Error messages appear below the field, in `--color-danger`, prefixed with an icon.
+- Placeholders are example values (`jane@example.com`), never instructions ("Enter your email").
+- Help text and error text share the same vertical slot — no layout shift between states.
+
+### card
+
+Background: `--color-surface`.
+Border: 1px solid `--color-border` (NOT shadow).
+Radius: `lg` (12px).
+Padding: 24px.
+
+Rules:
+
+- Cards group related content. Don't use a card for a single piece of content.
+- Cards in a list are separated by 16px vertical gaps. No additional shadows or dividers.
+- Hoverable cards get `--color-border-strong` on hover, no shadow.
+- Never nest cards more than one level deep.
+
+### badge
+
+Height: 24px.
+Padding: 0 8px.
+Radius: `full`.
+Text: 12px, weight 500.
+
+Variants:
+
+- `neutral` — slate-100 background, slate-700 text
+- `primary` — primary-subtle background, primary text
+- `success` — emerald-50 background, emerald-700 text
+- `warning` — amber-50 background, amber-700 text
+- `danger` — red-50 background, red-700 text
+- `info` — blue-50 background, blue-700 text
+
+Rules:
+
+- Badges are for status, counts, or labels. Never for navigation, never for actions.
+- Never use a badge as a button. If it's clickable, it's a button.
+- Never put more than one badge on a single piece of content unless they encode different information types (status + count is fine; two statuses is not).
+
+### modal
+
+Default max-width: 480px.
+Wide variant: 640px.
+Full variant: 90vw (only for large media or complex flows).
+Backdrop: `rgba(15, 23, 42, 0.5)`.
+Padding: 24px.
+Radius: `lg`.
+Shadow: `shadow-elevated`.
+
+Required close affordances (ALL THREE):
+
+- Close button (X) in the top-right
+- Click on backdrop dismisses
+- `Esc` key dismisses
+
+Rules:
+
+- Modals interrupt the user — only use them for short, focused tasks.
+- NEVER nest modals inside modals. Redesign the flow.
+- NEVER require horizontal scroll inside a modal.
+- Modal title is required. Plain language, sentence case.
+- Primary action is bottom-right. Cancel is bottom-left or the top-right X.
+- Destructive modals follow the pattern in `### destructive-actions`.
+
+### toast
+
+Position: bottom-right on desktop, top-center on mobile.
+Width: 360px max.
+Padding: 16px.
+Radius: `md`.
+Shadow: `shadow-elevated`.
+Stack: max 3 visible at once. Older toasts dismiss when the 4th appears.
+
+Auto-dismiss timing:
+
+- Success: 4 seconds
+- Info: 5 seconds
+- Warning: 7 seconds
+- Error: 10 seconds
+- With required action (e.g. "Undo"): never auto-dismiss until clicked
+
+Rules:
+
+- Toasts are for confirmations and non-critical errors. Never for blocking information.
+- Toasts always include an icon matching the variant.
+- Toasts NEVER contain "view more" links — the message must stand alone.
+- Errors that need user action go inline or as a banner — NOT as a toast.
+
+---
+
+## UX Patterns
+
+### navigation
+
+- 5+ top-level sections → sidebar (left, fixed, 240px wide)
+- 2–4 views → tabs (top of content, underline style)
+- Hierarchy beyond 2 levels deep → breadcrumbs (above the page title)
+
+Rules:
+
+- Hamburger menus are FORBIDDEN on screens ≥1024px wide.
+- Sidebar nav items are vertical icons + text. Never icon-only on desktop.
+- Active state: brand color text + brand color subtle background. NOT a colored bar.
+- Tabs: underline only, no background fill. Active tab gets brand color underline + text.
+- Breadcrumbs: separator is `/`, never `>`. Last item is the current page (no link).
+
+### modals
+
+Use a modal when:
+
+- The task is short (under 30 seconds)
+- The task is focused (single clear outcome)
+- The task interrupts the current flow intentionally (confirmation, quick edit)
+
+Use a new page when:
+
+- The task has multiple steps
+- The task requires reference to other content on the page
+- The task IS the primary flow (creating the main resource of the app)
+
+Forbidden:
+
+- Modal nested inside a modal
+- Modal that opens another modal on success
+- Modal taller than the viewport with internal scroll AND a sticky footer
+- Modal without a close X button
+
+### forms
+
+Layout:
+
+- Single column by default, ALWAYS. Two-column only when fields are paired (first/last name, city/zip).
+- Field gap: 16px vertical.
+- Section gap (within a form): 32px.
+
+Labels:
+
+- Above the field, always visible. Sentence case. Singular ("Project name", not "Project Names:").
+- No colon at the end.
+
+Optional vs required:
+
+- Mark OPTIONAL fields with `(optional)` after the label.
+- Never mark required fields with `*` or "required".
+
+Validation:
+
+- On `blur`, NEVER on keystroke (one exception: password strength meters).
+- On submit if the user has not yet blurred the field.
+- Error message below the field, in danger color, prefixed with icon.
+
+Submit button:
+
+- Bottom-right by default.
+- Cancel button to its left, secondary or ghost variant.
+- Submit label is always verb + object: "Create project", not "Submit" or "OK".
+
+Forbidden:
+
+- "Reset" buttons. Use Cancel instead.
+- Submit disabled until the form is valid (the user can't tell what's missing).
+- Multiple submit buttons.
+
+### loading
+
+Apply by perceived task duration:
+
+| Estimated time | Treatment |
+| --- | --- |
+| < 100ms | Nothing. Feels instant. |
+| 100ms – 1s | Nothing visible, OR a brief shimmer if the user might wonder. |
+| 1s – 3s | Inline spinner OR skeleton if the shape is known. |
+| 3s+ | Progress bar + descriptive text ("Importing 1,200 rows…") |
+| Unknown duration | Skeleton if shape known, indeterminate spinner with text otherwise. |
+
+Rules:
+
+- Skeleton vs spinner: skeleton if you know the shape (a card grid, a table, a profile). Spinner if you don't.
+- NEVER show a spinner AND a skeleton on the same content at the same time.
+- Loading replaces the content. Don't overlay a spinner on stale content unless the action is a refresh.
+- Loading on a button: spinner replaces the label inline; button width stays the same.
+
+### empty-states
+
+ALWAYS four elements, in this order:
+
+1. **Illustration** — small (max 120px tall), monochrome or low-contrast, never a photo.
+2. **Heading** — what the user is seeing, in 1 short sentence. "No projects yet."
+3. **Subtext** — what they can do about it, in 1 sentence. "Create your first project to start tracking work."
+4. **Primary CTA button** — verb + object. "Create project."
+
+Forbidden:
+
+- Empty area with no content
+- Generic "No data" string
+- Disabled CTA
+- More than one CTA (no "Learn more" + "Create" — pick one)
+- Apologetic tone ("Sorry, no items found")
+
+### errors
+
+Choose by error type:
+
+| Error | Treatment |
+| --- | --- |
+| Form validation | Inline, below the field |
+| Action failure (e.g. save failed) | Inline at the action point, OR top-of-form banner |
+| Page-level (5xx, network) | Top-of-page banner with retry button |
+| Critical, blocks all action | Full-page error state with retry CTA |
+
+Forbidden:
+
+- Errors as toasts (toasts auto-dismiss; the user might miss critical info)
+- Raw error codes ("Error 500") — translate to plain language
+- Error messages without next steps ("Something went wrong" — say WHAT and what to do)
+
+Plain language rule:
+
+- Always tell the user (a) what failed, (b) what to do next.
+- Bad: `Error: ENOENT no such file or directory`
+- Good: `Couldn't find the file. It may have been moved. Refresh the page or upload it again.`
+
+### destructive-actions
+
+Minimum 2 steps: trigger → confirmation.
+
+Confirmation modal copy format:
+
+```
+Title:    Delete [resource type]?
+Body:     This will permanently delete [resource name]. This cannot be undone.
+Cancel:   Cancel
+Danger:   Delete [resource type]
+```
+
+For HIGH-VALUE destructive actions (deleting a workspace, an account, paid data):
+
+- Require typed confirmation: "Type [resource name] to confirm"
+- Disable the danger button until the typed input matches exactly
+
+After success:
+
+- If reversible within a window: show an undo toast for 10 seconds.
+- If irreversible: show a success toast confirming what was deleted, no undo.
+
+Forbidden:
+
+- Single-click delete with no confirmation
+- "Are you sure?" with an OK button (vague + non-destructive button color)
+- Confirmations where the danger and cancel buttons look similar
+
+### data-tables
+
+Pagination:
+
+- Show pagination at 25+ rows.
+- Default page size: 25. Allowed: 25 / 50 / 100.
+- Page navigation: bottom-right. Total count: bottom-left.
+
+Sorting:
+
+- Click the column header to sort. Click again to reverse. Click a third time to clear.
+- Sort indicator: arrow up/down icon next to the column label.
+
+Filtering:
+
+- Filters live ABOVE the table, left-aligned.
+- Filter chips show active filters; X to remove.
+- "Clear all filters" appears when 2+ filters are active.
+
+Bulk actions:
+
+- Row selection via leading checkbox.
+- Bulk action bar appears above the table when 1+ rows selected.
+- Bulk action bar shows: count selected, available actions, "deselect all".
+
+Column behavior:
+
+- Sticky first column when horizontal scroll is needed.
+- Truncate long values with `…` and a tooltip showing the full value on hover.
+- Right-align numbers, left-align text and dates.
+
+Forbidden:
+
+- Horizontal scroll without sticky first column
+- Pagination AND infinite scroll on the same table
+- Sortable columns without a visible sort indicator
+
+### notifications
+
+Three types — never use the wrong one.
+
+| Type | Use for | Position | Persistence |
+| --- | --- | --- | --- |
+| **Toast** | Transient confirmation (saved, sent, copied) | Bottom-right | Auto-dismiss |
+| **Banner** | Persistent state info (trial ending, system maintenance) | Top of page | Dismissible by user |
+| **Inline** | Field-level feedback (validation error, status near a control) | Adjacent to the control | Persists until resolved |
+
+Rules:
+
+- Critical errors NEVER use toasts. Use a banner or inline error.
+- Banners stack at the top in priority order — most critical first.
+- Inline notifications never auto-dismiss.
+
+---
+
+## Flows
+
+### empty-state
+
+Steps:
+
+1. Route loads. Detect empty data.
+2. Render the empty state component (illustration + heading + subtext + CTA — see UX Patterns → empty-states).
+3. CTA leads DIRECTLY to the create flow. No intermediate "welcome" screen.
+4. After successful creation, route back to the populated view with a success toast: "[Resource] created."
+
+Anti-patterns:
+
+- Empty state that just says "Loading…" for a second before content appears (use a skeleton instead)
+- Empty state with multiple CTAs ("Create" AND "Learn more")
+- Empty state that disables the CTA until the user completes onboarding
+
+### onboarding
+
+Philosophy: minimum viable onboarding. Skip is ALWAYS allowed.
+
+Steps:
+
+1. **Welcome screen** — one sentence about what the product does. One primary CTA: "Get started." One secondary: "Skip."
+2. **Minimum collection** — name + primary use case. NO MORE THAN 2 INPUTS. If you need 5 fields, your onboarding is wrong.
+3. **One contextual highlight** — when the user lands on the main view, point at the most important thing with a small popover. Just one. Dismissible.
+4. **Mark as onboarded** — never show the onboarding again, even if the user clears state.
+
+Forbidden:
+
+- Multi-step wizards with 5+ screens
+- Required onboarding (no skip allowed)
+- Tutorial overlays that grey out the screen and block interaction
+- Asking for payment, phone number, or company size in onboarding
+
+### auth
+
+Steps:
+
+1. **Single screen, sign-in OR sign-up** — one email field. The button auto-detects: "Sign in" if account exists, "Create account" if not.
+2. **Authentication method** — magic link OR password OR OAuth. NEVER show all three side by side. Pick one primary, others as smaller text-link alternatives.
+3. **After auth** — route to the user's last intended destination. Default: dashboard.
+4. **Errors are inline** — never in a toast. "Wrong password" appears below the password field.
+
+Forbidden:
+
+- Separate "Sign in" and "Sign up" pages with identical fields
+- Forced password complexity requirements visible before the user has typed anything
+- "Remember me" checkboxes (assume yes — provide a sign-out instead)
+- CAPTCHA on the first login attempt
+
+---
+
+## Copy Rules
+
+**Voice**: direct, human, never cute. Closest reference: Linear, Stripe, Vercel.
+**Tense**: present.
+**Person**: second person (you / your).
+
+### Errors
+
+- Tell the user (a) what failed, (b) what to do next.
+- Never show error codes ("Error 500", "ENOENT", etc.). Translate.
+- Bad: `Failed to fetch.`
+- Good: `Couldn't load your projects. Check your connection and try again.`
+
+### CTAs
+
+- Format: verb + object. "Create project", "Send invite", "Delete account."
+- Forbidden: "Submit", "OK", "Click here", "Continue" (when the action is destructive or specific).
+
+### Empty states
+
+- Encouraging, not apologetic.
+- Bad: `Sorry, no projects found.`
+- Good: `No projects yet. Create your first to get started.`
+
+### Tooltips
+
+- One sentence max.
+- No trailing punctuation.
+- Bad: `This will permanently delete the selected items. This action cannot be undone.`
+- Good: `Delete the selected items`
+
+### Placeholders
+
+- Example values, never instructions.
+- Bad: `Enter your email`
+- Good: `jane@example.com`
+
+### Labels
+
+- Sentence case, singular.
+- No colons at the end.
+- Bad: `PROJECT NAMES:`
+- Good: `Project name`
+
+### Headings
+
+- Title case for H1 page titles. Sentence case for H2/H3 section headings.
+- Maximum 5 words for H1.
+
+### Numbers
+
+- Spell out one through nine in body copy. Use numerals for 10+.
+- Always use numerals in UI labels, table cells, and stats.
+
+---
+
+## Principles
+
+These are the north stars. When two rules conflict, the one closer to the top wins.
+
+### 1. Accessibility is not a feature
+
+WCAG AA minimum, no exceptions. Contrast enforced at the token level. ARIA
+landmarks on every route. Keyboard reachable for every interactive element.
+Focus-visible rings on everything that can be tabbed to. If your design fails
+accessibility, it fails — period.
+
+### 2. One primary action per screen
+
+If the user lands on a screen and there are two equally important things to
+do, redesign the screen. Secondary actions are visually subordinate. No
+competing CTAs. The user should never have to ask "what's the main thing here?"
+
+### 3. Error prevention over recovery
+
+Design so mistakes are hard to make in the first place. Default to safe
+inputs. Make destructive actions require deliberate effort (typed confirmation
+for high-value cases). Surface validation early enough that the user can fix
+it before they commit.
+
+### 4. Progressive disclosure
+
+Show what the user needs RIGHT NOW. Reveal more on demand. The default view
+is the most common case. Power features live one click deeper. A user should
+be able to ignore 80% of the interface 80% of the time.
+
+### 5. Copy drives decisions
+
+Write the copy before designing the UI. If the copy is vague, the UI is wrong.
+If the heading takes 3 seconds to understand, no font choice will save it.
+Test by reading aloud — if it sounds like a robot, rewrite it.
+
+### 6. Keyboard navigable by default
+
+Every interactive element is reachable via Tab in logical order. Every
+interactive element shows a visible focus ring when focused. Esc dismisses
+overlays (modals, popovers, dropdowns). Enter submits the focused form.
+Arrow keys navigate within components (tabs, menus, listboxes).
+
+### 7. Trust the system
+
+Don't second-guess these rules to "make it pop" or "match the brand." The
+brand is your color and your typography. Everything else is consistent across
+all UXonFly-built apps so your AI doesn't drift between sessions. If a rule
+is wrong, fix it in this file — don't override it case by case.