ai-developer-skill-os 7.5.0 → 8.1.4

package/skills/qk-ui-audit/SKILL.md

@@ -1,314 +0,0 @@
----
-name: qk-ui-audit
-category: qa
-version: 7.5.0
-description: "Kiểm toán giao diện (UI) với 57-point Anti-Slop checklist — fail nếu score < 90/100."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-execution_mode: deterministic
-
-cost: medium
-latency: medium
-risk: low
-side_effects: read_only
-produces: [report]
-consumes: [design-md, source-code]
-
-token_budget:
-  max_files_read: 5
-  max_lines_per_read: 150
-  max_shell_commands: 0
-  stop_early: true
-
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-# qk-ui-audit — Anti-Slop UI Inspector
-
-> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Preconditions
-- [ ] `DESIGN.md` exists in project root
-- [ ] Target UI file(s) or component(s) are specified
-
-```
-On missing precondition:
-  EXIT: BLOCKED
-  Message: "DESIGN.md not found. Run qk-project-bootstrap to create one, or provide design tokens manually."
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Scope
-- ✅ Score UI components against DESIGN.md tokens
-- ✅ Detect generic AI-slop aesthetics
-- ✅ Verify ARIA roles and contrast ratios
-- ✅ Validate responsive, interactive, and animation states
-
-## Non-Goals
-- ❌ Fix the UI — only audit and report (fixes go to qk-design-to-code)
-- ❌ Pixel-level screenshot comparison
-- ❌ Read entire CSS files — use targeted reads
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Priority Order
-
-| Priority | Category | Points | Skip Threshold |
-|----------|----------|--------|----------------|
-| P1 | Accessibility (ARIA, contrast, keyboard) | 15pts | Never |
-| P2 | Layout & Spacing (tokens, grid, whitespace) | 15pts | Budget < 30% |
-| P3 | Typography & Colors (DESIGN.md compliance) | 15pts | Budget < 50% |
-| P4 | Interactions & Animations (hover, focus, transitions) | 15pts | Budget < 60% |
-| P5 | Anti-Slop Detection (generic templates, slop colors) | 15pts | Budget < 70% |
-| P6 | Performance & Best Practices | 10pts | Budget < 80% |
-| BONUS | Mobile & Cross-browser | 5pts extra | Always optional |
-
-**Total: 85 base + 5 bonus = 90 possible. Pass threshold: ≥ 90/100**
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Workflow
-
-### Phase 1 — Load Design Contract
-
-**Steps:**
-1. `grep_search` for DESIGN.md → read color tokens, spacing scale, typography
-2. Extract key tokens: primary colors (HSL), spacing unit, font families, border-radius, shadow levels
-
-**Exit When:**
-- Tokens extracted → go to Phase 2
-- DESIGN.md empty or incomplete → EXIT: BLOCKED
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-### Phase 2 — Scan Target UI
-
-**Steps:**
-1. `view_file[targeted]` — read component file(s), focus on className, style, and JSX structure
-2. Check against each Priority category in order (P1 → P6)
-3. Log each finding with Evidence Format
-
-**Decision:**
-```
-IF score accumulates ≥ 90 after P1+P2+P3
-  → Can skip P4–P6 if token budget < 40%
-  → EXIT: PARTIAL (pass, but incomplete audit noted)
-
-IF CRITICAL violation found (e.g., hardcoded password in UI, broken ARIA)
-  → STOP audit, report immediately
-  → EXIT: FAILED
-```
-
-**Exit When:**
-- All categories checked → go to Phase 3
-- Token budget < 20% → go to Phase 3 with PARTIAL flag
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-### Phase 3 — Score & Report
-
-**Steps:**
-1. Calculate total score per category
-2. Identify top 3 most impactful fixes
-3. Generate report with Evidence Format entries
-
-**Decision:**
-```
-IF total score ≥ 90
-  → EXIT: SUCCESS
-
-IF total score 70–89
-  → EXIT: PARTIAL — list required fixes
-
-IF total score < 70
-  → EXIT: FAILED — demand redesign, not patch
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Confidence Model
-
-| Level | Condition | Action |
-|-------|-----------|--------|
-| HIGH | Token clearly absent/present, ARIA attribute visible | Report directly |
-| MEDIUM | Inferred from surrounding code patterns | Note assumption |
-| LOW | Cannot verify without rendering (e.g., animation timing) | Mark as "unverifiable — manual check required" |
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Severity
-
-| Level | Definition | Example |
-|-------|-----------|---------|
-| CRITICAL | Accessibility violation blocking disabled users | Missing alt text, contrast ratio < 3:1 |
-| HIGH | Design system contract broken | Hardcoded hex color not in DESIGN.md |
-| MEDIUM | UX degraded, workaround exists | Missing hover state, no loading indicator |
-| LOW | Minor inconsistency | Spacing off by 1 unit |
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Evidence Format
-
-```
-[SEVERITY] path/to/Component.tsx:LINE
-Category:   [Accessibility|Layout|Typography|Interaction|Anti-Slop|Performance]
-Reason:     [specific violation description]
-Confidence: [HIGH|MEDIUM|LOW]
-Fix:        [one-line actionable suggestion]
-Points:     -N pts
-```
-
-**Example:**
-```
-[HIGH] src/components/Button.tsx:23
-Category:   Typography
-Reason:     font-size hardcoded as "16px" — should use DESIGN.md token `--font-size-base`
-Confidence: HIGH
-Fix:        Replace with `var(--font-size-base)`
-Points:     -3 pts
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Retry Policy
-```
-Audit is read-only — no retry needed.
-If file is inaccessible → note as PARTIAL and continue with other files.
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Escalation Rules
-
-```
-BLOCKED: DESIGN.md missing or unreadable
-Missing:
-  - DESIGN.md with color tokens, spacing scale, typography definition
-Questions:
-  1. Có file design system nào khác không? (tokens.css, theme.ts, etc.)
-  2. Bạn có thể cung cấp màu sắc / font / spacing chính của dự án không?
-Recommended Assumptions (if proceeding):
-  - Use industry-standard: 8px spacing unit, Inter font, neutral gray palette
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Handoff Contract
-
-### Consumes
-```json
-{
-  "from": "user or qk-orchestrator",
-  "required_fields": ["target_component_path", "design_md_path"],
-  "optional_fields": ["specific_checklist_categories"]
-}
-```
-
-### Produces
-```json
-{
-  "to": "qk-design-to-code (if fixes needed)",
-  "output_fields": ["audit_score", "violations_list", "top_3_fixes", "exit_code"]
-}
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Output Format
-
-```
-🎨 UI Audit Report
-─────────────────────────────────────────────────
-Component:   [path/to/component]
-DESIGN.md:   [found | not found]
-
-Scores:
-  P1 Accessibility:  [X/15]
-  P2 Layout:         [X/15]
-  P3 Typography:     [X/15]
-  P4 Interactions:   [X/15]
-  P5 Anti-Slop:      [X/15]
-  P6 Performance:    [X/10]
-  ─────────────────
-  Total:             [X/85] → [PASS ≥ 90% | FAIL < 90%]
-
-Violations (top priority first):
-  [SEVERITY] file:LINE — reason — Fix: suggestion (-Xpts)
-
-Top 3 Required Fixes:
-  1. [Most impactful fix]
-  2. [Second fix]
-  3. [Third fix]
-
-Verdict:     [PASS | FAIL — requires redesign]
-Exit Code:   [SUCCESS | PARTIAL | FAILED]
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Exit Codes
-
-| Code | Meaning | When |
-|------|---------|------|
-| SUCCESS | Score ≥ 90 — UI passes Anti-Slop | All checks done, no critical violations |
-| PARTIAL | Score 70–89 or incomplete audit | Some categories skipped due to token budget |
-| BLOCKED | DESIGN.md missing or target not specified | Cannot audit without design contract |
-| FAILED | Score < 70 or CRITICAL violation found | Generic slop detected, redesign required |
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## References
-- Full 57-point checklist: `references/anti-slop-checklist.md`
-
----
-

package/skills/qk-ui-audit/references/anti-slop-checklist.md

@@ -1,136 +0,0 @@
-# Anti-Slop Checklist — 57 Points
-> Referenced by: `qk-ui-audit/SKILL.md`
-> Purpose: Full inspection checklist for detecting generic AI-generated UI
-
----
-
-## Category P1: Accessibility (15 pts)
-
-| # | Check | Points | How to Verify |
-|---|-------|--------|---------------|
-| 1 | All images have `alt` text (non-empty, descriptive) | 2 | grep `alt=""` or `alt={` in JSX |
-| 2 | Color contrast ratio ≥ 4.5:1 (text) / 3:1 (large text) | 3 | Check computed HSL values vs background |
-| 3 | All interactive elements have `aria-label` if no visible text | 2 | grep for `<button>` without text content |
-| 4 | Focus states are visible — `outline: none` not used without replacement | 2 | Check CSS for `outline: none` |
-| 5 | Keyboard navigation works (Tab order logical) | 2 | `tabIndex` only for non-interactive elements |
-| 6 | `role` attributes used for non-semantic elements (div acting as button) | 2 | grep `onClick` on non-button elements |
-| 7 | Form inputs have associated `<label>` (htmlFor) | 2 | grep `<input` without surrounding `<label` |
-
----
-
-## Category P2: Layout & Spacing (15 pts)
-
-| # | Check | Points | How to Verify |
-|---|-------|--------|---------------|
-| 8 | No hardcoded pixel spacing — uses design token scale (4, 8, 16, 24...) | 3 | grep `padding: [0-9]px` or `margin: [0-9]px` |
-| 9 | CSS Grid or Flexbox used — no `position: absolute` for layout | 2 | grep `position: absolute` in layout context |
-| 10 | Consistent spacing unit (not mixing 5px, 7px, 11px random values) | 2 | Check spacing values across components |
-| 11 | No `div` soup — semantic HTML used (article, section, nav, main, aside) | 2 | grep excessive `<div>` nesting |
-| 12 | Component has defined max-width (not stretching to 100vw on desktop) | 2 | Check container max-width |
-| 13 | Whitespace feels intentional — content is not cramped | 2 | Visual check or spacing scale adherence |
-| 14 | No horizontal overflow on mobile (320px viewport) | 2 | Check for `overflow-x: hidden` band-aids |
-
----
-
-## Category P3: Typography & Colors (15 pts)
-
-| # | Check | Points | How to Verify |
-|---|-------|--------|---------------|
-| 15 | Font families from DESIGN.md only (no Times New Roman, Arial default) | 3 | grep `font-family:` vs DESIGN.md |
-| 16 | Font sizes use token scale — no arbitrary px values | 2 | grep `font-size: [0-9]` raw values |
-| 17 | Colors use DESIGN.md tokens — no hardcoded hex (#ff0000) or rgb() | 3 | grep `#[0-9a-fA-F]{3,6}` in CSS/JSX |
-| 18 | No pure black (#000000) or pure white (#ffffff) — use near-black/near-white | 2 | grep `#000\|#000000\|#fff\|#ffffff` |
-| 19 | Color palette is harmonious — not "rainbow slop" (5+ unrelated colors) | 2 | Count distinct hues in palette |
-| 20 | Heading hierarchy correct — one `<h1>` per page, no skipping levels | 1 | grep heading tags per page |
-| 21 | Line height appropriate (1.4–1.7 for body, 1.1–1.3 for headings) | 2 | Check `line-height` values |
-
----
-
-## Category P4: Interactions & Animations (15 pts)
-
-| # | Check | Points | How to Verify |
-|---|-------|--------|---------------|
-| 22 | Every button has hover state — color shift OR shadow change | 2 | grep `:hover` for button styles |
-| 23 | Every button has focus-visible state | 2 | grep `:focus-visible` |
-| 24 | Active/pressed state exists for clickable elements | 1 | grep `:active` |
-| 25 | Transition duration from DESIGN.md — not raw `0.3s` everywhere | 2 | grep `transition:` vs token values |
-| 26 | No janky instant state changes — all transitions ≥ 100ms, ≤ 400ms | 2 | grep transition durations |
-| 27 | Animations respect `prefers-reduced-motion` | 2 | grep `prefers-reduced-motion` in CSS |
-| 28 | Links have hover underline OR color change (not just cursor pointer) | 2 | grep `a:hover` styles |
-| 29 | Form validation feedback uses animation (shake, pulse) not just color | 2 | Check error state CSS |
-
----
-
-## Category P5: Anti-Slop Detection (15 pts)
-
-| # | Check | Points | How to Verify |
-|---|-------|--------|---------------|
-| 30 | No Bootstrap/generic UI kit classes (btn-primary, card, badge) | 2 | grep `class="btn\|card\|badge\|modal"` |
-| 31 | No Tailwind utility spam (> 15 classes on single element) | 2 | grep extremely long className strings |
-| 32 | No Lorem Ipsum or placeholder text in production UI | 3 | grep `Lorem ipsum\|placeholder text` |
-| 33 | Color palette is NOT blue-gray default (slop signature) | 2 | Check if primary color is `hsl(210, *)` Tailwind default |
-| 34 | Layout is NOT a simple centered card on white background (slop template) | 2 | Structural check |
-| 35 | Gradient usage is intentional — not `linear-gradient(to bottom, #fff, #f0f0f0)` | 2 | grep gradient definitions |
-| 36 | No `box-shadow: 0 2px 4px rgba(0,0,0,0.1)` everywhere (Bootstrap shadow) | 2 | grep this exact shadow pattern |
-
----
-
-## Category P6: Performance & Best Practices (10 pts)
-
-| # | Check | Points | How to Verify |
-|---|-------|--------|---------------|
-| 37 | Images have `loading="lazy"` for below-fold content | 2 | grep `<img` without `loading` |
-| 38 | No `!important` overrides (except CSS reset) | 1 | grep `!important` in component CSS |
-| 39 | No inline styles except dynamic values | 2 | grep `style={{` in non-dynamic contexts |
-| 40 | Component file ≤ 300 lines | 1 | Line count check |
-| 41 | No unused CSS classes or dead styles | 1 | Visual code scan |
-| 42 | SVG icons used instead of emoji for UI elements | 1 | grep emoji characters in JSX |
-| 43 | `key` prop used correctly in lists (not index as key for dynamic lists) | 2 | grep `.map(` + check key prop |
-
----
-
-## Category BONUS: Mobile & Cross-Browser (5 pts extra)
-
-| # | Check | Points | How to Verify |
-|---|-------|--------|---------------|
-| 44 | Touch targets ≥ 44×44px on mobile | 1 | Check button/link dimensions |
-| 45 | No hover-only interactions (mobile has no hover) | 1 | Check if critical info only on hover |
-| 46 | Custom fonts have system-ui fallback | 1 | Check font-family fallback stack |
-| 47 | Input types correct: email, tel, number, date (triggers correct mobile keyboard) | 1 | grep `<input type=` |
-| 48 | No `position: fixed` elements blocking content on small screens | 1 | Check fixed/sticky headers/footers |
-
----
-
-## Extended Checks (9 additional points for comprehensive audit)
-
-| # | Check | Category |
-|---|-------|---------|
-| 49 | Loading skeleton matches actual content shape (not generic gray bars) | UX |
-| 50 | Empty state has illustration + helpful action button (not just "No data") | UX |
-| 51 | Error state specifies the error — not generic "Something went wrong" | UX |
-| 52 | Success feedback is clear — confirmation message or visual indicator | UX |
-| 53 | Destructive actions (delete) require confirmation dialog | Safety |
-| 54 | Modals/dialogs have accessible `role="dialog"` + focus trap | A11y |
-| 55 | Scrollable areas have visible scroll indicator | UX |
-| 56 | Data tables have sortable columns if > 10 rows | UX |
-| 57 | Forms have autofocus on first input (modal forms) | UX |
-
----
-
-## Scoring Summary
-
-| Category | Max Points |
-|----------|-----------|
-| P1 Accessibility | 15 |
-| P2 Layout & Spacing | 15 |
-| P3 Typography & Colors | 15 |
-| P4 Interactions & Animations | 15 |
-| P5 Anti-Slop Detection | 15 |
-| P6 Performance | 10 |
-| **Base Total** | **85** |
-| BONUS Mobile | +5 |
-| Extended (49–57) | +9 |
-| **Maximum Possible** | **99** |
-
-**Pass threshold: ≥ 76 / 85 base (90%) — PASS**
-**Fail: < 76 / 85 — requires redesign, not patch**

package/skills/qk-ui-system-builder/SKILL.md

@@ -1,221 +0,0 @@
----
-name: qk-ui-system-builder
-category: frontend
-version: 7.5.0
-description: "Xây dựng Design System và token library từ DESIGN.md — không tự đặt ra token ngoài contract."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-execution_mode: deterministic
-cost: medium
-latency: medium
-risk: low
-side_effects: edit_files
-produces: [code, tokens]
-consumes: [design-md]
-token_budget:
-  max_files_read: 2
-  max_lines_per_read: 100
-  max_shell_commands: 0
-  stop_early: true
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-# qk-ui-system-builder — Design System Constructor
-
-> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
-
----
-
-## Preconditions
-- [ ] `DESIGN.md` exists with color, spacing, typography tokens
-
-```
-On missing precondition:
-  EXIT: BLOCKED
-  Message: "DESIGN.md missing. Run qk-project-bootstrap to create one."
-```
-
----
-
-## Scope
-- ✅ Extract tokens from DESIGN.md ONLY — never invent
-- ✅ Generate CSS custom properties (variables) or framework theme
-- ✅ Ensure all components are accessible (A11y)
-
-## Non-Goals
-- ❌ Invent tokens not in DESIGN.md (e.g., standard Tailwind defaults)
-- ❌ Create duplicate tokens for same visual value
-- ❌ Generate component library without token foundation
-
----
-
-## Token Naming Convention
-
-```css
-/* Colors — HSL always */
---color-[role]-[shade]: hsl(H, S%, L%);
-/* Example: */
---color-primary-500: hsl(220, 80%, 55%);
---color-surface-100: hsl(220, 15%, 98%);
-
-/* Spacing — scale-based */
---space-[n]: [n * base]px;
-/* Example: */
---space-1: 4px; --space-2: 8px; --space-4: 16px;
-
-/* Typography */
---font-[family]: '[Name]', fallback;
---font-size-[scale]: [value]rem;
---font-weight-[name]: [value];
-
-/* Border Radius */
---radius-[size]: [value]px;
-
-/* Shadows */
---shadow-[level]: [value];
-
-/* Animation */
---duration-[speed]: [value]ms;
---ease-[type]: [cubic-bezier or keyword];
-
-/* Z-index */
---z-[layer]: [value];  /* dropdown=100, modal=200, toast=300 */
-```
-
----
-
-## Dark/Light Mode Pattern
-```css
-:root {
-  --color-background: hsl(0, 0%, 100%);
-  --color-text: hsl(220, 15%, 10%);
-}
-
-[data-theme="dark"] {
-  --color-background: hsl(220, 15%, 10%);
-  --color-text: hsl(220, 10%, 90%);
-}
-```
-
----
-
-## Workflow
-
-### Phase 1 — Extract from DESIGN.md
-1. Read DESIGN.md → list all defined tokens
-2. Categorize: Colors / Spacing / Typography / Radius / Shadow / Animation
-
-### Phase 2 — Generate Token File
-1. Create `src/styles/tokens.css` (or equivalent)
-2. Apply naming convention above
-3. Add dark mode variants if DESIGN.md specifies
-
-### Phase 3 — Verify No Invented Tokens
-1. Cross-check: every generated token has source in DESIGN.md
-2. Flag any token that was "inferred" vs explicitly defined
-
-**Decision:**
-```
-IF all tokens sourced from DESIGN.md → EXIT: SUCCESS
-IF some tokens inferred (MEDIUM confidence) → EXIT: PARTIAL, list them
-```
-
----
-
-
----
-
-## Priority Order
-
-
----
-
-## Output Format
-
-
----
-## Exit Codes
-| Code | Meaning | When |
-|------|---------|------|
-| SUCCESS | All tokens extracted from DESIGN.md, naming convention applied | All generated |
-| PARTIAL | Some tokens inferred (not explicitly in DESIGN.md) | Inferred values used |
-| BLOCKED | DESIGN.md missing or has no tokens | Cannot start |
-| FAILED | Token conflicts detected (duplicate values, naming collision) | Conflict |
-
----
-
-## Confidence Model
-| Level | Condition | Action |
-|-------|-----------|--------|
-| HIGH | Token explicitly exists in DESIGN.md | Extract and map |
-| MEDIUM | Token value inferred or estimated based on related tokens | Note assumption |
-| LOW | Core scale missing entirely (e.g. no spacing definition) | EXIT: BLOCKED |
-
----
-
-## Severity
-| Level | Definition | Example |
-|-------|-----------|---------|
-| CRITICAL | Hardcoded values injected without being tokens | Missing the point of the system |
-| HIGH | Token naming convention violated | `primary-color` instead of `--color-primary` |
-| MEDIUM | Dark mode not supported | Hardcoded white background |
-| LOW | Unused token generated | Extraneous variables |
-
----
-
-## Evidence Format
-```
-[SEVERITY] src/styles/tokens.css:LINE
-Issue:      [specific violation or gap]
-Confidence: HIGH
-Fix:        [specific change]
-```
-
----
-
-## Retry Policy
-```
-Token generation fails
-  └─ Check if naming collision or syntax error
-       ├─ Syntax error → fix CSS/SCSS format → retry
-       └─ Collision → deduplicate → retry
-            └─ Do NOT auto-retry more than 1 time
-```
-
----
-
-## Escalation Rules
-```
-BLOCKED: DESIGN.md missing or empty
-Missing:
-  - Valid DESIGN.md with token specifications
-Questions:
-  1. Bạn có file design reference nào khác không?
-Recommended Assumptions:
-  - Generate default Tailwind-like scale if requested
-```
-
----
-
-## Handoff Contract
-### Consumes
-```json
-{
-  "from": "user or project-bootstrap",
-  "required_fields": ["design_md_path"],
-  "optional_fields": ["css_framework", "output_format"]
-}
-```
-### Produces
-```json
-{
-  "to": "user or design-to-code",
-  "output_fields": ["token_file_path", "inferred_tokens", "exit_code"]
-}
-```
-
----
-
-