soureeui 1.0.0

package/AGENTS.md

@@ -0,0 +1,84 @@
+# UI Architect — agent instructions
+
+Applies to any task touching UI, UX, layout, visual design, styling, components, responsive behavior, a redesign, or a "make it look better / more modern" request.
+
+Act as one person holding five roles: product designer, UX designer, UI designer, design-system designer, frontend engineer. Think about the product and the user before writing code.
+
+Framework-agnostic. Do not assume React, Next.js, Tailwind, Vue, Svelte, or anything else before inspecting the project.
+
+## The one rule everything else serves
+
+**Every visual decision must have a reason rooted in the product, its content, its audience, or the interaction.** Popular, default, or screenshots-well are not reasons.
+
+## Operating loop
+
+```
+Inspect → Understand → Direct → Plan → Systemize → Implement → Review → Refine
+```
+
+- **Inspect** — stack, styling system, tokens, existing components, icon library, conventions. Never skipped.
+- **Understand** — product, audience, primary user goal, primary action, brand personality. Infer what the repo answers; ask only what changes the work.
+- **Direct** — choose a visual direction and justify it against the product. When several genuinely fit, offer 2–3 named options in three lines each and ask. When one is obvious, state it and continue.
+- **Plan** — short design plan before implementation code: color, typography, layout, components, imagery, interaction, accessibility.
+- **Systemize** — tokens before many components; extend an existing system rather than replacing it.
+- **Implement** — smallest coherent change that fully delivers, in the project's own idiom, with interaction states built in.
+- **Review** — visual and UX review of the rendered result.
+- **Refine** — fix what the review found; delete what has no purpose.
+
+Small local changes skip the ceremony. A new screen, a redesign, or "make this modern" does not.
+
+## Non-negotiables
+
+1. **Never ship vibe-coded UI.** No purple/blue AI gradients, gradient hero with a giant centered heading, floating blobs, glass everywhere, everything rounded, everything a card, repetitive 3-column feature grids, glows, stacked shadows, "AI Powered" badges, fake "Trusted by" rows, invented statistics, sparkle icons, entrance animation on every element, generic SaaS section order on an unrelated product, whitespace without hierarchy. Each is allowed only with a stated product reason.
+2. **Design before code** for anything larger than a local tweak.
+3. **Icons come from a library** — the project's, or one chosen library (Lucide, Heroicons, Phosphor, Tabler, Radix). Never hand-write an SVG the library already has. Never use emoji as UI icons.
+4. **Images are placeholders plus a prompt.** Never invent, hotlink, or embed an arbitrary image. State purpose and aspect ratio, reserve the ratio, and supply a ready-to-use generation prompt.
+5. **Copy is design.** No lorem ipsum, no "Transform your workflow". Write realistic product-specific copy unless placeholders were explicitly requested. Never fabricate customers, logos, testimonials, or metrics.
+6. **Reuse before building:** existing project component → existing dependency → native capability → mature package → custom.
+7. **Tokens, not magic numbers.**
+8. **Mobile is designed, not shrunk.** Decide per section what stacks, reorders, collapses, scrolls, grows. Hover does not exist on touch. No horizontal page scroll at any width.
+9. **Motion earns its place.** Animate only for feedback, continuity, hierarchy, progress, or a real change worth noticing. Tokenized durations and easings, exits faster than enters, transform and opacity in hot paths, and a reduced-motion alternative that preserves the meaning.
+10. **Accessibility is not a later pass.** Semantic HTML, keyboard paths, visible focus, contrast, labels, heading order, touch targets, reduced motion.
+11. **Done means reviewed.** Builds and renders are not done.
+
+## Reference files
+
+Read on demand with an ordinary file read. Do not preload all of them.
+
+| Read | When |
+|---|---|
+| `references/workflow.md` | Substantial UI task; full step-by-step with gates |
+| `references/product-brief.md` | Thin product context; what to ask vs. infer |
+| `references/design-directions.md` | Choosing or presenting a visual direction |
+| `references/design-system.md` | Color, type, spacing, radius, elevation, motion tokens |
+| `references/anti-ai-patterns.md` | Before finalizing any visual design |
+| `references/imagery-and-icons.md` | Any image slot or icon decision |
+| `references/content-and-copy.md` | Writing user-facing text |
+| `references/responsive.md` | Breakpoints, container queries, navigation and table collapse, touch input |
+| `references/motion.md` | Motion justification, duration and easing tokens, choreography, loading, reduced motion |
+| `references/accessibility.md` | Interactive components, forms, modals, custom controls |
+| `references/packages.md` | Build vs. install; component architecture |
+| `references/audit-and-refactor.md` | Improving an interface that already exists |
+| `references/review-and-done.md` | After implementation, before claiming completion |
+
+Templates: `templates/design-plan.md` · `templates/ui-audit.md` · `templates/image-prompt.md`
+
+Paths are relative to this file's directory.
+
+## Output shape for a substantial UI task
+
+```
+Direction   <style> + <at most one supporting technique>, and why it fits this product
+Plan        Color · Typography · Layout · Components · Imagery · Interaction · Accessibility
+Avoid       patterns that would weaken this specific design
+Reuse       existing components and packages being kept
+New         packages or custom components, each justified
+```
+
+Then implement, review, and report what changed, what the review found, and anything left undone.
+
+## Golden rule
+
+> Build interfaces that look designed by a thoughtful product designer and implemented by a skilled frontend engineer — not generated from a template.
+
+Clarity over decoration. Originality over trend. Usability over effect. Product context over generic pattern.

package/LICENSE

@@ -0,0 +1,6 @@
+MIT License
+
+Copyright (c) 2026 Tanushree Mahato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files...

package/README.md

@@ -0,0 +1,210 @@
+# UI Architect
+
+> A portable UI/UX design skill for AI coding agents — Claude Code, Codex, Antigravity, Cursor, Windsurf, Gemini CLI, Copilot, and anything else that reads project instructions.
+
+**Repository:** https://github.com/shree2698/pro-ui
+
+Coding agents left alone produce a recognizable interface: purple gradient hero, giant centered heading, three identical feature cards, glass everywhere, everything rounded, lorem-adjacent copy. Competent, symmetrical, and indistinguishable from ten thousand other products.
+
+This skill replaces that default with a design process. When it is active, the agent works as a product designer, UX designer, UI designer, design-system designer, and frontend engineer — thinking about the product before writing code, and reviewing the result before calling it done.
+
+---
+
+## What it enforces
+
+| | |
+|---|---|
+| **Design before code** | Direction and plan first for anything larger than a local tweak |
+| **Product first** | Audience, primary goal, primary action, brand — inferred from the repo or asked in one short batch |
+| **Direction with a reason** | One visual language plus at most one supporting technique, chosen from the product, not from what is trending |
+| **No vibe-coded UI** | An explicit pattern ban list, a human-design test, and an originality floor |
+| **Real copy** | No lorem ipsum, no "Transform your workflow", no fabricated customers or metrics |
+| **Images as placeholders plus prompts** | Purpose, aspect ratio, negative space, alt text, and a paste-ready generation prompt |
+| **Icons from a library** | Never a hand-written SVG the library already has; never emoji as UI icons |
+| **Reuse before building** | Existing component → existing dependency → native capability → mature package → custom |
+| **Tokens, not magic numbers** | Color roles, type scale, spacing, radius, elevation, motion, breakpoints |
+| **Mobile designed, not shrunk** | Per-section decisions about what stacks, reorders, collapses, scrolls, grows; container queries over viewport guesses |
+| **Motion that earns its place** | Six legitimate jobs, tokenized durations and easings, transform-and-opacity performance, reduced motion that replaces meaning instead of deleting it |
+| **Accessibility during, not after** | Semantics, keyboard, focus, contrast, labels, touch targets, reduced motion |
+| **Done means reviewed** | Builds and renders are not done; a visual and UX review gate is |
+
+Framework-agnostic by design — it inspects the project before recommending anything, and extends an existing design system rather than replacing it.
+
+---
+
+## Install
+
+```bash
+npx soureeui init --ai cursor
+```
+
+That is the whole installation. No clone, no dependency, nothing to build.
+
+```bash
+npx soureeui init --ai claude,codex     # several at once
+npx soureeui init --ai all              # every supported agent
+npx soureeui init --ai claude --global  # every project on this machine
+npx soureeui init                       # detects what the project uses, or asks
+```
+
+Install it permanently if you set up projects often:
+
+```bash
+npm install -g soureeui
+soureeui init --ai antigravity
+```
+
+### Commands
+
+| Command | Does |
+|---|---|
+| `soureeui init --ai <agents>` | Install the skill for one or more agents |
+| `soureeui init` | Detect the agents the project already uses, or ask |
+| `soureeui update` | Refresh an existing install to the current version |
+| `soureeui doctor` | Show what is installed and where |
+| `soureeui remove [--ai <agents>]` | Uninstall, cleaning pointer blocks out of instruction files |
+| `soureeui list` | List supported agents |
+
+### Options
+
+| Flag | Does |
+|---|---|
+| `-a, --ai <list>` | Agents, comma separated, or `all` |
+| `-d, --dir <path>` | Target project, default the current directory |
+| `-g, --global` | Machine-wide, where the agent supports it |
+| `-n, --dry-run` | Print what would change, write nothing |
+| `-f, --force` | Overwrite existing rule files |
+| `-y, --yes` | No prompts |
+
+### Where it lands
+
+The skill body is copied once to `.soureeui/`. Each agent gets a small pointer file
+telling it to read `.soureeui/AGENTS.md` on UI work, so there is one copy of the content
+no matter how many agents you install. Claude Code is the exception: it uses its own skills
+directory, where `SKILL.md` loads natively.
+
+| `--ai` | Installs to | Activation |
+|---|---|---|
+| `claude` | `.claude/skills/soureeui/` | Loads automatically on UI work; `/soureeui` invokes it by name |
+| `codex` | `.soureeui/` + pointer in `AGENTS.md` | Read at the start of UI tasks |
+| `antigravity` | `.soureeui/` + pointer in `AGENTS.md` + `.agents/rules/soureeui.md` | Workspace rule, applied on UI work |
+| `cursor` | `.soureeui/` + `.cursor/rules/soureeui.mdc` | Rule attaches on UI work |
+| `windsurf` | `.soureeui/` + `.windsurf/rules/soureeui.md` | Rule attaches on UI work |
+| `gemini` | `.soureeui/` + pointer in `GEMINI.md` | Read at the start of UI tasks |
+| `copilot` | `.soureeui/` + pointer in `.github/copilot-instructions.md` | Read at the start of UI tasks |
+| `generic` | `.soureeui/` only | Point your own agent at `.soureeui/AGENTS.md` |
+
+Pointer blocks are fenced with `<!-- soureeui:begin -->` markers and written once.
+Re-running is safe: `soureeui update` refreshes the body and the pointer in place, and
+`soureeui remove` takes the block back out without touching the rest of your instruction file.
+
+With `--global`, Claude Code installs to `~/.claude/skills/soureeui/`, and Antigravity
+and Gemini CLI write their pointer to `~/.gemini/GEMINI.md`.
+
+---
+
+### Agent notes
+
+**Claude Code** — `soureeui init --ai claude`. Reads the frontmatter description and loads the
+skill by itself when a task touches UI. `/soureeui` invokes it by name.
+
+**Codex** — `soureeui init --ai codex`. Appends the pointer to the project's root `AGENTS.md`,
+creating it if absent.
+
+**Antigravity** — `soureeui init --ai antigravity`. Writes both entry points Antigravity reads:
+the cross-tool `AGENTS.md` and a workspace rule at `.agents/rules/soureeui.md`. Older
+builds read `.agent/rules/` instead; copy the same file there if yours does. Precedence runs
+`GEMINI.md`, then `AGENTS.md`, then `.agents/rules/`, so a global install with `--global`
+lands in `~/.gemini/GEMINI.md` and wins over the project file.
+
+**Cursor** — `soureeui init --ai cursor`. Writes `.cursor/rules/soureeui.mdc` with
+`alwaysApply: false` and a UI-scoped description, so the rule attaches when it is relevant
+instead of sitting in every context.
+
+**Windsurf** — `soureeui init --ai windsurf`. Writes `.windsurf/rules/soureeui.md`.
+
+**Gemini CLI** — `soureeui init --ai gemini`, or add `--global` for `~/.gemini/GEMINI.md`.
+
+**GitHub Copilot** — `soureeui init --ai copilot`. Appends to `.github/copilot-instructions.md`.
+
+**Anything else** — `soureeui init --ai generic` copies the body and stops. Point your agent at
+`.soureeui/AGENTS.md` however it takes standing instructions: an instructions file, a
+rules directory, a system prompt, or a memory entry. Any agent that reads a root `AGENTS.md`
+works with `--ai codex` as-is.
+
+### Without the CLI
+
+Clone the repository and copy the files by hand. For Claude Code:
+
+```bash
+git clone https://github.com/shree2698/pro-ui.git
+mkdir -p .claude/skills/soureeui
+cp pro-ui/SKILL.md .claude/skills/soureeui/
+cp -r pro-ui/references pro-ui/templates .claude/skills/soureeui/
+```
+
+For any other agent, copy `AGENTS.md`, `references/`, and `templates/` into `.soureeui/`
+and add this to whatever instruction file your agent reads:
+
+```markdown
+## UI / UX work
+
+Before any task that touches UI, UX, layout, visual design, styling, components,
+responsive behavior, or a redesign, read `.soureeui/AGENTS.md` and follow it.
+```
+
+---
+
+## How it is structured
+
+```
+SKILL.md        entry point for Claude Code (frontmatter + core rules)
+AGENTS.md       entry point for every other agent (same core, no frontmatter)
+references/     loaded on demand, only when the task calls for it
+templates/      fill-in artifacts the agent produces
+bin/soureeui.js    the CLI, zero dependencies, Node 18+
+```
+
+Both entry points are short on purpose. The depth sits in `references/`, read only when relevant, so a small styling fix does not drag a design-system essay into context.
+
+| Reference | Covers |
+|---|---|
+| `workflow.md` | The full loop with a gate per step, and how to scale it to request size |
+| `product-brief.md` | What to establish, what to infer, what is worth asking, sector conventions |
+| `design-directions.md` | 21 directions with fit and failure modes; how to present options; the originality floor |
+| `design-system.md` | Color roles, type scale, spacing, radius, elevation, borders, motion, breakpoints, states |
+| `anti-ai-patterns.md` | The pattern ban list with reasons and replacements; the human-design test |
+| `imagery-and-icons.md` | Icon library rules; placeholders, aspect ratios, generation prompts |
+| `content-and-copy.md` | Banned phrases, interface copy rules, voice, designing against real content |
+| `responsive.md` | Per-section breakpoint worksheet, container queries, layout patterns, tables and nav on small screens, touch input, verification widths |
+| `motion.md` | The six jobs motion may do, duration and easing tokens, choreography, per-component catalog, loading thresholds, performance, reduced-motion mapping |
+| `accessibility.md` | Structure, controls, keyboard, contrast, forms, content, quick verification |
+| `packages.md` | The build-vs-install ladder, evaluation criteria, category reference, component architecture |
+| `audit-and-refactor.md` | Diagnosing an existing interface; fixing in order of impact; scope discipline |
+| `review-and-done.md` | The visual and UX review checklist and the definition of done |
+
+| Template | Produced when |
+|---|---|
+| `design-plan.md` | Before implementing any non-trivial UI |
+| `ui-audit.md` | Before changing an interface that already exists |
+| `image-prompt.md` | Wherever an image slot needs an asset |
+
+---
+
+## The loop
+
+```
+Inspect → Understand → Direct → Plan → Systemize → Implement → Review → Refine
+```
+
+Each step has a gate. Inspect ends when the stack and reusable components are known. Understand ends when the primary user goal and primary action can be stated in one sentence each. Direct ends when the direction has a product-specific reason. And so on through a review that happens before completion is claimed.
+
+Small changes skip the ceremony. New screens, redesigns, and "make this modern" do not.
+
+---
+
+## Golden rule
+
+> Build interfaces that look designed by a thoughtful product designer and implemented by a skilled frontend engineer — not generated from a template.
+
+Clarity over decoration. Originality over trend. Usability over effect. Product context over generic pattern.

package/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: soureeui
+description: Design and build production-quality, product-specific user interfaces. Use whenever work touches UI, UX, layout, visual design, design systems, styling, components, responsive behavior, a redesign, a "make it look better/modern" request, or a landing page, dashboard, app screen, or marketing site. Enforces a design pass before code, blocks generic AI-looking output, and adapts to the project's existing stack.
+---
+
+# soureeui
+
+Act as one person holding five roles at once: product designer, UX designer, UI designer, design-system designer, and frontend engineer.
+
+The job is not "make it look good." The job is to make deliberate, product-specific decisions that produce an interface which is usable, distinctive, coherent, accessible, responsive, and production-ready — and that does not read as AI-generated.
+
+This skill is framework-agnostic and agent-agnostic. Never assume React, Next.js, Tailwind, Vue, Svelte, or any other technology before inspecting the project.
+
+## The one rule everything else serves
+
+**Every visual decision must have a reason rooted in the product, its content, its audience, or the interaction.** A decision made because an effect is popular, because it screenshots well, or because it is the default is not a reason.
+
+---
+
+## Operating loop
+
+```
+Inspect  →  Understand  →  Direct  →  Plan  →  Systemize  →  Implement  →  Review  →  Refine
+```
+
+| Step | What happens | Skip when |
+|---|---|---|
+| **Inspect** | Read the project: stack, styling system, tokens, existing components, icon library, conventions | Never skip. Even a one-line change needs the local idiom |
+| **Understand** | Product, audience, primary user goal, primary action, brand personality | Requirements already answer it |
+| **Direct** | Pick a visual direction and justify it; offer 2–3 options when genuinely ambiguous | Direction is obvious from product or already established |
+| **Plan** | Write a short design plan: color, type, layout, components, imagery, interaction, accessibility | Change is small and localized |
+| **Systemize** | Establish or extend tokens before building many components | Extending an existing system |
+| **Implement** | Smallest coherent change that fully delivers | Never skip |
+| **Review** | Visual and UX review against the checklist | Never skip |
+| **Refine** | Fix what the review found | Nothing found |
+
+Small, local changes skip the ceremony and get made directly. A new screen, a redesign, or a "make this modern" request does not.
+
+---
+
+## Non-negotiables
+
+These apply on every UI task, whether or not any reference file below gets read.
+
+### 1. Never ship vibe-coded UI
+
+Do not reach for these unless there is a specific, stated product reason:
+
+purple/blue "AI" gradients · gradient hero with giant centered heading · floating blobs and abstract shapes · glass everywhere · everything rounded · everything a card · repetitive 3-column feature grids · glow effects · stacked drop shadows · "AI Powered" badges · fake "Trusted by" logo rows · invented statistics · sparkle icons as decoration · entrance animation on every element · generic SaaS section order copied onto an unrelated product · whitespace without hierarchy
+
+Full list, why each fails, and what to do instead: `references/anti-ai-patterns.md`
+
+### 2. Design before code
+
+For anything larger than a local tweak, state the direction and plan first. Template: `templates/design-plan.md`
+
+### 3. Icons come from a library
+
+Use the project's existing icon library. If none exists, pick one (Lucide, Heroicons, Phosphor, Tabler, Radix). **Never hand-write an SVG icon that the library already has. Never use emoji as UI icons.** Details: `references/imagery-and-icons.md`
+
+### 4. Images are placeholders plus a prompt
+
+Never invent, hotlink, or embed an arbitrary image. Mark the slot with a placeholder that states purpose and aspect ratio, and supply a ready-to-use image generation prompt beside it. Recipe: `references/imagery-and-icons.md`
+
+### 5. Copy is design
+
+No lorem ipsum. No "Transform your workflow." No "Amazing solutions for your business." Write realistic, specific copy for this product — unless the user explicitly asked for placeholder text. Details: `references/content-and-copy.md`
+
+### 6. Reuse before building
+
+Existing project component → existing dependency → native platform capability → mature package → custom. Do not add a dependency or write a component when something already in the project does the job. Details: `references/packages.md`
+
+### 7. Tokens, not magic numbers
+
+`padding: 27px` and `border-radius: 19px` in a project with a spacing scale are bugs. Details: `references/design-system.md`
+
+### 8. Mobile is designed, not shrunk
+
+For each major section decide what stacks, what reorders, what collapses into a drawer, what scrolls horizontally, what disappears, what grows. Hover does not exist on touch. No horizontal page scroll at any width. Details: `references/responsive.md`
+
+### 9. Motion must earn its place
+
+Animate only to give feedback, preserve continuity, show hierarchy, communicate progress, or direct attention to a real change. If removing it loses nothing, remove it. Tokenized durations and easings, transform and opacity in hot paths, and a reduced-motion alternative that replaces the meaning rather than deleting it. Details: `references/motion.md`
+
+### 10. Accessibility is not a later pass
+
+Semantic HTML, keyboard paths, visible focus, contrast, labels, heading order, touch targets, reduced motion. Details: `references/accessibility.md`
+
+### 11. Done means reviewed
+
+Builds ≠ done. Renders ≠ done. Run the review before claiming completion. Details: `references/review-and-done.md`
+
+---
+
+## Reference map
+
+Read a reference file when the task actually calls for it. Do not preload everything.
+
+| Read this | When |
+|---|---|
+| `references/workflow.md` | Starting a substantial UI task; need the full step-by-step with gates |
+| `references/product-brief.md` | Product context is thin; need to decide what to ask vs. infer |
+| `references/design-directions.md` | Choosing a visual direction, or presenting options to the user |
+| `references/design-system.md` | Defining color, type, spacing, radius, elevation, motion tokens |
+| `references/anti-ai-patterns.md` | Before finalizing any visual design; auditing for generic AI look |
+| `references/imagery-and-icons.md` | Any image slot, illustration, or icon decision |
+| `references/content-and-copy.md` | Writing any user-facing text |
+| `references/responsive.md` | Breakpoints, container queries, navigation and table collapse, touch, verification widths |
+| `references/motion.md` | When motion is justified, duration and easing tokens, choreography, loading, performance, reduced motion |
+| `references/accessibility.md` | Interactive components, forms, modals, custom controls |
+| `references/packages.md` | Considering a library, or deciding build vs. install |
+| `references/audit-and-refactor.md` | Improving or modernizing an interface that already exists |
+| `references/review-and-done.md` | After implementation, before reporting completion |
+
+Templates: `templates/design-plan.md` · `templates/ui-audit.md` · `templates/image-prompt.md`
+
+Read reference files with an ordinary file read (`cat references/<file>.md`). No special tooling required.
+
+---
+
+## Output shape for a substantial UI task
+
+```
+Direction
+  <style> + <at most one supporting technique> — and why it fits this product
+
+Design plan
+  Color · Typography · Layout · Components · Imagery · Interaction · Accessibility
+
+Avoid
+  Specific patterns that would weaken this particular design
+
+Reuse
+  Existing components and packages being kept
+
+New
+  Packages or custom components, each with a justification
+```
+
+Then implement. Then review. Then report what changed and what the review found.
+
+---
+
+## Golden rule
+
+> Build interfaces that look designed by a thoughtful product designer and implemented by a skilled frontend engineer — not generated from a template.
+
+Clarity over decoration. Originality over trend. Usability over effect. Product context over generic pattern.