soureeui 1.0.0

package/bin/soureeui.js

@@ -0,0 +1,491 @@
+#!/usr/bin/env node
+'use strict'
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const readline = require('readline')
+
+const PKG = require('../package.json')
+const ROOT = path.resolve(__dirname, '..')
+const PAYLOAD = ['AGENTS.md', 'SKILL.md', 'references', 'templates']
+const BODY_DIR = '.soureeui'
+const MARK_BEGIN = '<!-- soureeui:begin -->'
+const MARK_END = '<!-- soureeui:end -->'
+
+const POINTER = (bodyPath) => `${MARK_BEGIN}
+## UI / UX work
+
+Before any task that touches UI, UX, layout, visual design, styling, components,
+responsive behavior, or a redesign, read \`${bodyPath}\` and follow it. It defines
+the design process, the anti-generic-UI rules, and the reference files to load on demand.
+${MARK_END}`
+
+const CURSOR_RULE = `---
+description: UI/UX design process for any interface, layout, styling, component, or redesign work
+globs:
+alwaysApply: false
+---
+
+Read \`${BODY_DIR}/AGENTS.md\` and follow it for any task touching UI, UX, layout,
+visual design, styling, components, responsive behavior, or a redesign. It defines
+the design process, the anti-generic-UI rules, and reference files to load on demand.
+`
+
+// agent registry -------------------------------------------------------------
+
+const claudeSkillDir = (ctx) => ctx.global
+  ? path.join(os.homedir(), '.claude', 'skills', 'soureeui')
+  : path.join(ctx.dir, '.claude', 'skills', 'soureeui')
+
+const AGENTS = {
+  claude: {
+    label: 'Claude Code',
+    detect: ['.claude', 'CLAUDE.md'],
+    install: (ctx) => {
+      ctx.copyBody(claudeSkillDir(ctx), { skill: true })
+      ctx.note('loads automatically on UI work, or run /soureeui')
+    },
+    paths: (ctx) => [claudeSkillDir(ctx)],
+  },
+  codex: {
+    label: 'Codex',
+    detect: ['AGENTS.md', '.codex'],
+    install: (ctx) => {
+      ctx.body()
+      ctx.pointer(path.join(ctx.dir, 'AGENTS.md'))
+    },
+    paths: (ctx) => [path.join(ctx.dir, BODY_DIR), path.join(ctx.dir, 'AGENTS.md')],
+  },
+  antigravity: {
+    label: 'Antigravity',
+    detect: ['.agents', '.agent'],
+    install: (ctx) => {
+      ctx.body()
+      ctx.pointer(ctx.global
+        ? path.join(os.homedir(), '.gemini', 'GEMINI.md')
+        : path.join(ctx.dir, 'AGENTS.md'))
+      ctx.write(path.join(ctx.dir, '.agents', 'rules', 'soureeui.md'),
+        POINTER(`${BODY_DIR}/AGENTS.md`) + '\n')
+    },
+    paths: (ctx) => [
+      path.join(ctx.dir, BODY_DIR),
+      path.join(ctx.dir, '.agents', 'rules', 'soureeui.md'),
+      path.join(ctx.dir, 'AGENTS.md'),
+    ],
+  },
+  cursor: {
+    label: 'Cursor',
+    detect: ['.cursor'],
+    install: (ctx) => {
+      ctx.body()
+      ctx.write(path.join(ctx.dir, '.cursor', 'rules', 'soureeui.mdc'), CURSOR_RULE)
+    },
+    paths: (ctx) => [path.join(ctx.dir, BODY_DIR), path.join(ctx.dir, '.cursor', 'rules', 'soureeui.mdc')],
+  },
+  windsurf: {
+    label: 'Windsurf',
+    detect: ['.windsurf'],
+    install: (ctx) => {
+      ctx.body()
+      ctx.write(path.join(ctx.dir, '.windsurf', 'rules', 'soureeui.md'),
+        POINTER(`${BODY_DIR}/AGENTS.md`) + '\n')
+    },
+    paths: (ctx) => [path.join(ctx.dir, BODY_DIR), path.join(ctx.dir, '.windsurf', 'rules', 'soureeui.md')],
+  },
+  gemini: {
+    label: 'Gemini CLI',
+    detect: ['GEMINI.md', '.gemini'],
+    install: (ctx) => {
+      ctx.body()
+      ctx.pointer(ctx.global
+        ? path.join(os.homedir(), '.gemini', 'GEMINI.md')
+        : path.join(ctx.dir, 'GEMINI.md'))
+    },
+    paths: (ctx) => [path.join(ctx.dir, BODY_DIR), path.join(ctx.dir, 'GEMINI.md')],
+  },
+  copilot: {
+    label: 'GitHub Copilot',
+    detect: [path.join('.github', 'copilot-instructions.md')],
+    install: (ctx) => {
+      ctx.body()
+      ctx.pointer(path.join(ctx.dir, '.github', 'copilot-instructions.md'))
+    },
+    paths: (ctx) => [path.join(ctx.dir, BODY_DIR), path.join(ctx.dir, '.github', 'copilot-instructions.md')],
+  },
+  generic: {
+    label: 'Any other agent',
+    detect: [],
+    install: (ctx) => {
+      ctx.body()
+      ctx.note(`point your agent at ${BODY_DIR}/AGENTS.md`)
+    },
+    paths: (ctx) => [path.join(ctx.dir, BODY_DIR)],
+  },
+}
+
+const NAMES = Object.keys(AGENTS)
+
+// output ---------------------------------------------------------------------
+
+const ESC = String.fromCharCode(27)
+const tty = process.stdout.isTTY && !process.env.NO_COLOR
+const paint = (code, s) => (tty ? `${ESC}[${code}m${s}${ESC}[0m` : s)
+const bold = (s) => paint(1, s)
+const dim = (s) => paint(2, s)
+const green = (s) => paint(32, s)
+const yellow = (s) => paint(33, s)
+const red = (s) => paint(31, s)
+
+// piping into head/less closes stdout early; that is not an error
+process.stdout.on('error', (err) => { if (err.code === 'EPIPE') process.exit(0) })
+
+const log = (s = '') => process.stdout.write(s + '\n')
+const fail = (msg) => { process.stderr.write(red('error: ') + msg + '\n'); process.exit(1) }
+
+// args -----------------------------------------------------------------------
+
+function parseArgs (argv) {
+  const out = { _: [], ai: [], dir: process.cwd(), global: false, force: false, dryRun: false, yes: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    const next = () => {
+      const v = argv[++i]
+      if (v === undefined || v.startsWith('-')) fail(`${a} needs a value`)
+      return v
+    }
+    const addAi = (v) => out.ai.push(...v.split(',').map((s) => s.trim()).filter(Boolean))
+    if (a === '--ai' || a === '-a') addAi(next())
+    else if (a.startsWith('--ai=')) addAi(a.slice(5))
+    else if (a === '--dir' || a === '-d') out.dir = path.resolve(next())
+    else if (a.startsWith('--dir=')) out.dir = path.resolve(a.slice(6))
+    else if (a === '--global' || a === '-g') out.global = true
+    else if (a === '--force' || a === '-f') out.force = true
+    else if (a === '--dry-run' || a === '-n') out.dryRun = true
+    else if (a === '--yes' || a === '-y') out.yes = true
+    else if (a === '--help' || a === '-h') out.help = true
+    else if (a === '--version' || a === '-v') out.version = true
+    else if (a.startsWith('-')) fail(`unknown flag: ${a}`)
+    else out._.push(a)
+  }
+  return out
+}
+
+// fs helpers -----------------------------------------------------------------
+
+function copyDir (src, dest) {
+  fs.mkdirSync(dest, { recursive: true })
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name)
+    const to = path.join(dest, entry.name)
+    if (entry.isDirectory()) copyDir(from, to)
+    else fs.copyFileSync(from, to)
+  }
+}
+
+function makeCtx (opts, actions) {
+  const ctx = {
+    dir: opts.dir,
+    global: opts.global,
+    rel: (p) => (p === opts.dir || p.startsWith(opts.dir + path.sep)
+      ? path.relative(opts.dir, p) || '.'
+      : p.replace(os.homedir(), '~')),
+    note: (msg) => actions.push({ kind: 'note', msg }),
+    write: (file, content) => actions.push({ kind: 'write', file, content }),
+    pointer: (file) => actions.push({ kind: 'pointer', file }),
+    copyBody: (dest, o = {}) => actions.push({ kind: 'body', dest, skill: !!o.skill }),
+    body: () => ctx.copyBody(path.join(opts.dir, BODY_DIR)),
+  }
+  return ctx
+}
+
+function applyActions (actions, opts, ctx) {
+  for (const a of actions) {
+    if (a.kind === 'note') {
+      log('  ' + dim(a.msg))
+      continue
+    }
+
+    if (a.kind === 'body') {
+      if (!opts.dryRun) {
+        fs.mkdirSync(a.dest, { recursive: true })
+        for (const item of PAYLOAD) {
+          const src = path.join(ROOT, item)
+          if (!fs.existsSync(src)) continue
+          const dest = path.join(a.dest, item)
+          if (fs.statSync(src).isDirectory()) {
+            fs.rmSync(dest, { recursive: true, force: true })
+            copyDir(src, dest)
+          } else {
+            fs.copyFileSync(src, dest)
+          }
+        }
+        fs.rmSync(path.join(a.dest, a.skill ? 'AGENTS.md' : 'SKILL.md'), { force: true })
+      }
+      log('  ' + green('+') + ' skill body ' + dim('->') + ' ' + ctx.rel(a.dest) + '/')
+      continue
+    }
+
+    if (a.kind === 'write') {
+      const exists = fs.existsSync(a.file)
+      if (exists && !opts.force && fs.readFileSync(a.file, 'utf8') === a.content) {
+        log('  ' + dim('=') + ' ' + ctx.rel(a.file) + ' ' + dim('already current'))
+        continue
+      }
+      if (!opts.dryRun) {
+        fs.mkdirSync(path.dirname(a.file), { recursive: true })
+        fs.writeFileSync(a.file, a.content)
+      }
+      log('  ' + green(exists ? '~' : '+') + ' ' + ctx.rel(a.file))
+      continue
+    }
+
+    if (a.kind === 'pointer') {
+      const bodyPath = opts.global
+        ? path.join(os.homedir(), BODY_DIR, 'AGENTS.md').replace(os.homedir(), '~')
+        : `${BODY_DIR}/AGENTS.md`
+      const block = POINTER(bodyPath)
+      const exists = fs.existsSync(a.file)
+      const current = exists ? fs.readFileSync(a.file, 'utf8') : ''
+
+      if (current.includes(MARK_BEGIN)) {
+        const start = current.indexOf(MARK_BEGIN)
+        const end = current.indexOf(MARK_END, start)
+        const next = current.slice(0, start) + block + current.slice(end + MARK_END.length)
+        if (next !== current && !opts.dryRun) fs.writeFileSync(a.file, next)
+        log('  ' + dim('=') + ' ' + ctx.rel(a.file) + ' ' +
+          dim(next === current ? 'already current' : 'pointer refreshed'))
+        continue
+      }
+
+      if (!opts.dryRun) {
+        fs.mkdirSync(path.dirname(a.file), { recursive: true })
+        const head = current ? current.replace(/\n*$/, '\n\n') : ''
+        fs.writeFileSync(a.file, head + block + '\n')
+      }
+      log('  ' + green(exists ? '~' : '+') + ' ' + ctx.rel(a.file) + ' ' +
+        dim(exists ? 'pointer appended' : 'created'))
+    }
+  }
+}
+
+// agent selection ------------------------------------------------------------
+
+function detect (dir) {
+  const found = []
+  for (const name of NAMES) {
+    for (const marker of AGENTS[name].detect) {
+      if (fs.existsSync(path.join(dir, marker))) {
+        found.push(name)
+        break
+      }
+    }
+  }
+  return found
+}
+
+function ask (question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    rl.question(question, (answer) => {
+      rl.close()
+      resolve(answer.trim())
+    })
+  })
+}
+
+async function pickAgents (opts) {
+  if (opts.ai.length) {
+    if (opts.ai.includes('all')) return NAMES.filter((n) => n !== 'generic')
+    const unknown = opts.ai.filter((n) => !NAMES.includes(n))
+    if (unknown.length) fail(`unknown agent: ${unknown.join(', ')}\n       known: ${NAMES.join(', ')}, all`)
+    return [...new Set(opts.ai)]
+  }
+
+  const found = detect(opts.dir)
+  const fallback = found.length ? found : ['claude', 'codex']
+
+  if (opts.yes || !process.stdin.isTTY) {
+    if (found.length) log(dim(`detected: ${found.join(', ')}`))
+    return fallback
+  }
+
+  log('')
+  log(bold('Which agents?') + dim('  numbers, names, or a for all'))
+  NAMES.forEach((n, i) => {
+    const hit = found.includes(n) ? green('  detected') : ''
+    log(`  ${dim(String(i + 1) + ')')} ${n.padEnd(12)} ${dim(AGENTS[n].label)}${hit}`)
+  })
+  const answer = await ask(`\n${dim('default: ' + fallback.join(', '))}\n> `)
+  if (!answer) return fallback
+  if (/^(a|all)$/i.test(answer)) return NAMES.filter((n) => n !== 'generic')
+
+  const picked = answer.split(/[\s,]+/).filter(Boolean).map((token) => {
+    const i = Number(token)
+    if (Number.isInteger(i) && i >= 1 && i <= NAMES.length) return NAMES[i - 1]
+    if (NAMES.includes(token)) return token
+    return fail(`not an option: ${token}`)
+  })
+  return [...new Set(picked)]
+}
+
+// commands -------------------------------------------------------------------
+
+async function cmdInit (opts) {
+  if (!fs.existsSync(opts.dir)) fail(`no such directory: ${opts.dir}`)
+  const agents = await pickAgents(opts)
+
+  log('')
+  log(`${bold('soureeui')} ${dim('v' + PKG.version)}  ${opts.dir}${opts.dryRun ? yellow('  dry run') : ''}`)
+  log('')
+
+  for (const name of agents) {
+    log(bold(AGENTS[name].label))
+    const actions = []
+    const ctx = makeCtx(opts, actions)
+    AGENTS[name].install(ctx)
+    applyActions(actions, opts, ctx)
+    log('')
+  }
+
+  log(green('Done.') + dim(' Ask your agent to build or redesign a screen and it will run the design process.'))
+  log('')
+}
+
+function cmdList () {
+  log('')
+  log(bold('Supported agents'))
+  NAMES.forEach((n) => log(`  ${n.padEnd(12)} ${dim(AGENTS[n].label)}`))
+  log('')
+  log(dim('  soureeui init --ai cursor'))
+  log(dim('  soureeui init --ai claude,codex'))
+  log(dim('  soureeui init --ai all'))
+  log('')
+}
+
+function installedPaths (name, ctx) {
+  return AGENTS[name].paths(ctx).filter((p) => {
+    if (!fs.existsSync(p)) return false
+    if (/\.(md|mdc)$/.test(p) && !p.includes('soureeui')) {
+      return fs.readFileSync(p, 'utf8').includes(MARK_BEGIN)
+    }
+    return true
+  })
+}
+
+function cmdDoctor (opts) {
+  log('')
+  log(`${bold('soureeui doctor')}  ${dim(opts.dir)}`)
+  log('')
+  const ctx = makeCtx(opts, [])
+  let any = false
+  for (const name of NAMES) {
+    const present = installedPaths(name, ctx)
+    if (!present.length) continue
+    any = true
+    log(`${green('installed')}  ${bold(AGENTS[name].label)}`)
+    present.forEach((p) => log(`           ${dim(ctx.rel(p))}`))
+  }
+  if (!any) log(dim('nothing installed here. run: soureeui init'))
+  log('')
+}
+
+async function cmdRemove (opts) {
+  const agents = opts.ai.length ? (opts.ai.includes('all') ? NAMES : opts.ai) : NAMES
+  const ctx = makeCtx(opts, [])
+  const targets = [...new Set(agents.flatMap((n) => installedPaths(n, ctx)))]
+
+  if (!targets.length) {
+    log(dim('nothing to remove.'))
+    return
+  }
+
+  log('')
+  log(bold('Will remove or clean:'))
+  targets.forEach((p) => log('  ' + ctx.rel(p)))
+  log('')
+
+  if (!opts.yes && !opts.dryRun && process.stdin.isTTY) {
+    const answer = await ask('Proceed? (y/N) ')
+    if (!/^y(es)?$/i.test(answer)) {
+      log(dim('cancelled.'))
+      return
+    }
+  }
+
+  for (const p of targets) {
+    const isInstructionFile = /\.(md|mdc)$/.test(p) && !p.includes('soureeui')
+    if (isInstructionFile) {
+      const content = fs.readFileSync(p, 'utf8')
+      const start = content.indexOf(MARK_BEGIN)
+      const end = content.indexOf(MARK_END, start)
+      const cleaned = (content.slice(0, start) + content.slice(end + MARK_END.length)).trim()
+      if (!opts.dryRun) {
+        if (cleaned) fs.writeFileSync(p, cleaned + '\n')
+        else fs.rmSync(p)
+      }
+      log('  ' + green('-') + ' pointer removed from ' + ctx.rel(p))
+    } else {
+      if (!opts.dryRun) fs.rmSync(p, { recursive: true, force: true })
+      log('  ' + green('-') + ' ' + ctx.rel(p))
+    }
+  }
+  log('')
+}
+
+function help () {
+  log(`
+${bold('soureeui')} ${dim('- install the UI Architect design skill into your AI coding agent')}
+
+${bold('Usage')}
+  soureeui init [--ai <agents>] [options]
+  soureeui list
+  soureeui doctor
+  soureeui remove [--ai <agents>]
+
+${bold('Examples')}
+  ${dim('$')} soureeui init --ai cursor
+  ${dim('$')} soureeui init --ai claude,codex
+  ${dim('$')} soureeui init --ai all
+  ${dim('$')} soureeui init --ai claude --global
+  ${dim('$')} soureeui init                    ${dim('detects what the project uses, or asks')}
+
+${bold('Agents')}
+  ${NAMES.join(', ')}, all
+
+${bold('Options')}
+  -a, --ai <list>    agents to install for, comma separated
+  -d, --dir <path>   target project (default: current directory)
+  -g, --global       install machine-wide, where the agent supports it
+  -f, --force        overwrite existing rule files
+  -n, --dry-run      show what would change, write nothing
+  -y, --yes          no prompts
+  -h, --help         this text
+  -v, --version      version
+`)
+}
+
+// main -----------------------------------------------------------------------
+
+async function main () {
+  const opts = parseArgs(process.argv.slice(2))
+  if (opts.version) return log(PKG.version)
+  const cmd = opts._[0] || (opts.ai.length ? 'init' : null)
+  if (opts.help || !cmd) return help()
+
+  switch (cmd) {
+    case 'init':
+    case 'install':
+    case 'add': return cmdInit(opts)
+    case 'update': return cmdInit({ ...opts, force: true })
+    case 'list':
+    case 'agents': return cmdList()
+    case 'doctor':
+    case 'status': return cmdDoctor(opts)
+    case 'remove':
+    case 'uninstall': return cmdRemove(opts)
+    default: return fail(`unknown command: ${cmd}\n       try: soureeui --help`)
+  }
+}
+
+main().catch((err) => fail(err && err.stack ? err.stack : String(err)))

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "soureeui",
+  "version": "1.0.0",
+  "description": "Install the UI Architect design skill into Claude Code, Codex, Antigravity, Cursor, Windsurf, Gemini CLI, or Copilot, so the agent designs before it codes instead of producing generic AI-looking UI.",
+  "bin": {
+    "soureeui": "bin/soureeui.js"
+  },
+  "files": [
+    "bin",
+    "references",
+    "templates",
+    "AGENTS.md",
+    "SKILL.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ui",
+    "ux",
+    "design",
+    "design-system",
+    "ai",
+    "agent",
+    "skill",
+    "claude-code",
+    "codex",
+    "antigravity",
+    "cursor",
+    "windsurf",
+    "copilot",
+    "agents-md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shree2698/pro-ui.git"
+  },
+  "homepage": "https://github.com/shree2698/pro-ui#readme",
+  "bugs": {
+    "url": "https://github.com/shree2698/pro-ui/issues"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "node bin/soureeui.js --help > /dev/null && node bin/soureeui.js list > /dev/null && echo ok"
+  }
+}

package/references/accessibility.md

@@ -0,0 +1,77 @@
+# Accessibility
+
+Part of the design, not a pass afterwards. Retrofitting is more expensive than building it correctly.
+
+Target: WCAG 2.2 AA unless the project states otherwise.
+
+---
+
+## Structure
+
+- semantic elements over styled generic containers: `button`, `a`, `nav`, `main`, `header`, `footer`, `section`, `ul`, `table`, `dialog`
+- one `h1` per page; heading levels descend without gaps. Rank is semantic — size is styling
+- landmarks so a screen reader can jump: main content, navigation, search, footer
+- a skip link to main content when navigation precedes it
+- lists are lists, tables are tables with real headers and scopes
+
+## Controls
+
+- **a button does something, a link goes somewhere.** Never a clickable `div`
+- icon-only controls carry an accessible name
+- toggles, tabs, menus, comboboxes, and dialogs expose their state (pressed, selected, expanded, current)
+- custom controls follow the established keyboard pattern for that role — if that is expensive, use a primitives library (`packages.md`)
+
+## Keyboard
+
+- every interactive element is reachable and operable by keyboard
+- tab order follows visual order
+- **visible focus on every focusable element.** Never remove the focus ring without replacing it with something at least as visible
+- focus-visible for keyboard users; do not show rings on mouse click if the project prefers that, but never suppress both
+- modals trap focus, close on Escape, and return focus to the trigger
+- no keyboard traps anywhere else
+
+## Contrast
+
+| Content | Minimum |
+|---|---|
+| Body text | 4.5:1 |
+| Large text (≥24px, or ≥19px bold) | 3:1 |
+| Icons and meaningful graphics | 3:1 |
+| Control boundaries, focus indicators | 3:1 against adjacent colors |
+
+Check at token-definition time. Placeholder text, muted text on tinted surfaces, and text over images are the usual failures — text over an image needs a scrim or a guaranteed-safe zone.
+
+**Color is never the only signal.** Pair it with text, icon, shape, or position — for status, validation, chart series, and required fields.
+
+## Forms
+
+- every field has a persistent visible label. Placeholder is not a label
+- errors are associated with the field, announced, and stated in text next to it
+- required fields marked in text, not by color or an unexplained asterisk alone
+- related controls grouped with a group label
+- appropriate input types and autocomplete hints
+- do not disable submit silently; explain what is missing
+
+## Content
+
+- alt text describes purpose, not appearance. Decorative images get empty alt
+- link text makes sense alone — "read the routing guide", not "click here"
+- captions and transcripts for media
+- dynamic updates announced through a polite live region; never hijack focus for a background update
+
+## Interaction
+
+- touch targets ~44px minimum with spacing between adjacent targets
+- do not rely on hover to reveal essential content or actions
+- respect reduced motion, and provide a reduced alternative rather than removing meaning (`motion.md`)
+- page stays usable at 200% zoom and at 320px effective width with no loss of content or function
+- do not suppress zoom
+
+## Quick verification
+
+1. Unplug the mouse. Complete the primary task.
+2. Tab through. Is focus always visible and in a sensible order?
+3. Zoom to 200%. Does anything break or get clipped?
+4. Check contrast on text, icons, and focus rings.
+5. Read only the headings. Does the page make sense?
+6. Turn on reduced motion. Is everything still understandable?

package/references/anti-ai-patterns.md

@@ -0,0 +1,74 @@
+# Anti-AI Patterns
+
+The failure mode this skill exists to prevent: an interface that is competent, symmetrical, glossy, and indistinguishable from ten thousand others.
+
+Read this before finalizing any visual design.
+
+---
+
+## The pattern list
+
+Each is banned as a *default*. Each is allowed when there is a stated product reason.
+
+| Pattern | Why it fails | Instead |
+|---|---|---|
+| Purple-to-blue gradient as brand | Belongs to no product; signals "generated" instantly | Derive color from the actual brand, product, or domain |
+| Gradient hero with giant centered heading | Zero information, maximum height, no hierarchy | Lead with the actual value proposition and a real interface or artifact |
+| Floating blobs / abstract shapes | Decoration standing in for content | Real imagery, real data, real product UI, or nothing |
+| Glow and neon halos | Attention without meaning | Contrast and position carry emphasis |
+| Glass everywhere | Layering with nothing to layer over; kills contrast | Glass only over actual imagery or depth |
+| Everything rounded to the same large radius | Erases hierarchy; every element reads the same weight | A radius system with intent (`design-system.md`) |
+| Every section is a card | Cards become the page instead of grouping content | Cards for genuinely discrete, repeated objects only |
+| Repetitive 3-column feature grid | Three features, equal weight, no priority — a lie about the product | Rank features; give the important one more space |
+| Stacked drop shadows | Fake depth with no light source | One elevation scale, used sparingly |
+| "AI Powered" / "Next-Gen" badges | Says nothing; dates instantly | Say what it does |
+| Fake "Trusted by" logo rows | Fabricated social proof | Real customers, or cut the section |
+| Invented statistics ("10x faster", "99.9%") | Fabricated claims | Real numbers, or qualitative specifics |
+| Sparkle icons as decoration | Meaningless glyph noise | Icons that label real actions |
+| Entrance animation on every element | Delays content; motion sickness; nothing is emphasized | Motion where it explains a change |
+| Constant floating / pulsing loops | Permanent distraction | Static, unless movement carries meaning |
+| Generic SaaS section order transplanted onto an unrelated product | Structure unrelated to this product's story | Section order from the actual user journey |
+| Whitespace without hierarchy | Airy but unreadable; nothing dominates | Space that groups and ranks |
+| Identical icon-title-text triplets down the page | Templated rhythm | Vary composition where content differs |
+| Emoji as UI icons | Inconsistent rendering, unprofessional, not accessible | Icon library (`imagery-and-icons.md`) |
+| Lorem ipsum or "Transform your workflow" | Design built on nothing | Real product copy (`content-and-copy.md`) |
+| Centered everything | No reading axis, no tension | Deliberate alignment; asymmetry where it helps |
+| Dark hero, light body, dark footer for no reason | Banded structure copied from templates | Structure from content |
+
+---
+
+## The human-design test
+
+Run every question. Any "yes" in the wrong direction is a fix, not a note.
+
+1. **Does it look like a template?** → Change composition, hierarchy, or type — not just color.
+2. **Could this belong to hundreds of unrelated products?** → Add product-specific decisions.
+3. **Are decorative effects louder than the content?** → Remove effects until content wins.
+4. **Are all the cards identical?** → Rank them, or stop using cards.
+5. **Is everything rounded?** → Rebuild the radius system.
+6. **Is it purple/blue with a gradient?** → Rebuild the palette from the product.
+7. **Does every element animate?** → Cut motion to what explains change.
+8. **Does every section have the same structure?** → Vary deliberately.
+9. **Would removing this element hurt?** → If no, remove it.
+10. **Can a stranger tell what the product does in five seconds?** → If no, the design is failing its first job.
+
+---
+
+## The originality floor
+
+Every interface needs at least **two decisions no competitor's site would share**. Usually one structural and one expressive:
+
+- a layout shaped by the actual workflow or data, not by a grid preset
+- a color taken from the physical product, material, domain, or existing brand
+- a type pairing with a reason from the sector's own visual history
+- a signature component that only this product needs
+- a density chosen for how these users actually work
+- a real artifact — screenshot, chart, map, document, photograph — instead of decoration
+
+Without those, the direction is a costume.
+
+---
+
+## Self-check before shipping
+
+Ask: *if this screenshot appeared in a feed with no caption, would anyone guess which product it belongs to?* If not, go back to the originality floor.