ai-developer-skill-os 7.0.2 → 7.5.1

package/skills/qk-ui-builder/references/themes/modern-minimal.md

@@ -0,0 +1,52 @@
+# Theme: Modern Minimal
+
+**Genre:** modern-minimal  
+**Use case:** SaaS, startups, portfolios
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | mid (30–85% lightness) |
+| Display style | geometric-sans |
+| Accent hue | neutral |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(220, 15%, 98%);
+  --color-surface: hsl(220, 15%, 100%);
+  --color-text: hsl(220, 20%, 12%);
+  --color-text-muted: hsl(220, 10%, 50%);
+  --color-accent: hsl(220, 15%, 45%);
+  --color-accent-hover: hsl(220, 15%, 38%);
+  --font-display: 'Inter', 'Helvetica Neue', sans-serif;
+  --font-body: 'Inter', 'Helvetica Neue', sans-serif;
+  --radius-sm: 6px;
+  --radius-md: 8px;
+  --shadow-sm: 0 1px 2px hsl(220, 15%, 90%);
+  --shadow-md: 0 4px 12px hsl(220, 15%, 90%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Workbench
+- ✅ Stat-Led
+- ✅ Index-First
+- ❌ Marquee Hero (too noisy)
+- ❌ Manifesto (too expressive)
+
+## Anti-Patterns (Modern Minimal-specific)
+
+- ❌ Decorative illustrations
+- ❌ Gradient buttons or backgrounds
+- ❌ More than 2 font families
+- ❌ Heavy drop shadows
+
+## Voice
+
+- Single-word actions: "Sign in", "Pricing", "Docs"
+- No decorative copy
+- Metrics and social proof prominent

package/skills/qk-ui-builder/references/themes/playful.md

@@ -0,0 +1,52 @@
+# Theme: Playful
+
+**Genre:** playful  
+**Use case:** games, kids, entertainment
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | light (85–100% lightness) |
+| Display style | rounded-sans |
+| Accent hue | warm (30–60°) |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(45, 60%, 97%);
+  --color-surface: hsl(45, 60%, 100%);
+  --color-text: hsl(45, 50%, 12%);
+  --color-text-muted: hsl(45, 20%, 45%);
+  --color-accent: hsl(35, 85%, 55%);
+  --color-accent-hover: hsl(35, 85%, 48%);
+  --font-display: 'Nunito', 'Varela Round', sans-serif;
+  --font-body: 'Nunito', 'Varela Round', sans-serif;
+  --radius-sm: 12px;
+  --radius-md: 16px;
+  --shadow-sm: 0 2px 4px hsl(45, 60%, 85%);
+  --shadow-md: 0 6px 16px hsl(45, 60%, 85%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Bento Grid
+- ✅ Marquee Hero
+- ✅ Feature Stack
+- ❌ Long Document (too text-heavy)
+- ❌ Quote-Led (too serious)
+
+## Anti-Patterns (Playful-specific)
+
+- ❌ Serious or corporate tones
+- ❌ Monochrome palettes
+- ❌ Minimal whitespace (dense layouts)
+- ❌ Sharp corners or rigid grids
+
+## Voice
+
+- Exclamation marks and emoji allowed
+- Action verbs: "Play", "Join", "Explore"
+- Friendly, inclusive language

package/skills/qk-ui-builder/references/themes/specimen.md

@@ -0,0 +1,52 @@
+# Theme: Specimen
+
+**Genre:** editorial  
+**Use case:** design systems, documentation
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | mid (30–85% lightness) |
+| Display style | high-contrast-serif |
+| Accent hue | neutral |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(40, 10%, 96%);
+  --color-surface: hsl(40, 10%, 100%);
+  --color-text: hsl(40, 15%, 8%);
+  --color-text-muted: hsl(40, 5%, 45%);
+  --color-accent: hsl(40, 5%, 45%);
+  --color-accent-hover: hsl(40, 5%, 38%);
+  --font-display: 'Playfair Display', Georgia, serif;
+  --font-body: 'Source Sans 3', 'Helvetica Neue', sans-serif;
+  --radius-sm: 4px;
+  --radius-md: 4px;
+  --shadow-sm: 0 1px 2px hsl(40, 15%, 90%);
+  --shadow-md: 0 4px 12px hsl(40, 15%, 90%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Type Specimen
+- ✅ Index-First
+- ✅ Component Playground
+- ❌ Marquee Hero (too playful)
+- ❌ Bento Grid (too casual)
+
+## Anti-Patterns (Specimen-specific)
+
+- ❌ Playful illustrations or mascots
+- ❌ Warm saturated accents (orange, coral)
+- ❌ Rounded corners > 4px
+- ❌ Gradient hero backgrounds
+
+## Voice
+
+- Typographic precision: "Style guide", "Type scale", "Spacing rhythm"
+- Noun-first labels: "Design tokens", "Component states"
+- Neutral, authoritative tone

package/skills/qk-ui-builder/references/themes/terminal.md

@@ -0,0 +1,52 @@
+# Theme: Terminal
+
+**Genre:** tech  
+**Use case:** CLI tools, developer tools, terminals
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | dark (0–30% lightness) |
+| Display style | mono |
+| Accent hue | phosphor green (120–150°) |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(220, 15%, 4%);
+  --color-surface: hsl(220, 15%, 8%);
+  --color-text: hsl(120, 30%, 75%);
+  --color-text-muted: hsl(120, 10%, 45%);
+  --color-accent: hsl(120, 60%, 55%);
+  --color-accent-hover: hsl(120, 60%, 48%);
+  --font-display: 'JetBrains Mono', 'Fira Code', monospace;
+  --font-body: 'JetBrains Mono', 'Fira Code', monospace;
+  --radius-sm: 0px;
+  --radius-md: 0px;
+  --shadow-sm: none;
+  --shadow-md: none;
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Workbench
+- ✅ Component Playground
+- ✅ Stat-Led
+- ❌ Manifesto (too expressive)
+- ❌ Photographic (too visual)
+
+## Anti-Patterns (Terminal-specific)
+
+- ❌ Serif or display fonts
+- ❌ Warm accent hues
+- ❌ Decorative shadows or borders
+- ❌ Smooth transitions/animations
+
+## Voice
+
+- Command-line syntax: `$ npm install`, `> init()`
+- Terse, imperative: "Run", "Deploy", "Configure"
+- Status codes and badges

package/skills/qk-ui-builder/references/typography.md

@@ -0,0 +1,129 @@
+# Typography
+
+Foundational rules for font selection, type scale, and textual hierarchy. These rules exist to guarantee readable, professional, and consistent type across every generated UI.
+
+## The 2+1 Rule
+
+Use **at most 2 font families + 1 monospace** per project. Exceeding this causes visual noise and slows load time.
+
+- **Display / Heading family** (1): used for titles, hero text.
+- **Body / UI family** (1): used for paragraphs, labels, controls.
+- **Monospace** (1, optional): used for code, IDs, numeric tables, logs.
+
+```css
+:root {
+  --font-display: "Playfair Display", Georgia, serif;
+  --font-body: "Inter", system-ui, sans-serif;
+  --font-mono: "JetBrains Mono", ui-monospace, monospace;
+}
+```
+
+If you only need one family, the body family can double as the display family. Do not introduce a third decorative family.
+
+## Font Catalog
+
+Pick from this approved catalog. Prefer fonts that share the same optical quality and load reliably via Google Fonts or system fallbacks.
+
+| Family | Role | Notes |
+| --- | --- | --- |
+| Inter | Body / UI | Neutral, legible at small sizes. Default choice. |
+| Source Serif 4 | Display / Body | Serif companion to Inter; good for reading-heavy UI. |
+| Playfair Display | Display | High-contrast serif for hero/editorial headings. |
+| JetBrains Mono | Mono | Developer-friendly monospace. |
+| Poppins | Display / UI | Geometric, friendly; use sparingly. |
+| Roboto / Roboto Flex | Body / UI | Safe system-adjacent alternative. |
+| IBM Plex Sans / Mono | Body / Mono | Corporate, consistent pairing. |
+
+Pairing examples that work:
+- **Inter + Playfair Display + JetBrains Mono** (editorial + code)
+- **Inter + Source Serif 4 + JetBrains Mono** (clean + reading)
+- **Poppins + Inter + JetBrains Mono** (friendly branding)
+
+## Type Scale
+
+Use only these sizes. Do not invent intermediate sizes.
+
+```
+12px   caption / meta
+14px   small text / secondary
+16px   body (base)
+18px   lead / intro paragraph
+24px   h3 / section title
+32px   h2 / page title
+48px   h1 / hero
+64px   display / marketing hero
+```
+
+```css
+:root {
+  --text-xs: 0.75rem;   /* 12px */
+  --text-sm: 0.875rem;  /* 14px */
+  --text-base: 1rem;    /* 16px */
+  --text-lg: 1.125rem;  /* 18px */
+  --text-xl: 1.5rem;    /* 24px */
+  --text-2xl: 2rem;     /* 32px */
+  --text-3xl: 3rem;     /* 48px */
+  --text-4xl: 4rem;     /* 64px */
+}
+```
+
+## Line Height
+
+| Content | Line height |
+| --- | --- |
+| Body text | **1.5** |
+| Headings (h1–h3) | **1.2** |
+| Tight display (64px) | 1.1 |
+
+```css
+p, li, label { line-height: 1.5; }
+h1, h2, h3 { line-height: 1.2; }
+```
+
+## Hierarchy
+
+Establish hierarchy with **size + weight + color**, not decoration.
+
+```css
+h1 { font-family: var(--font-display); font-size: var(--text-3xl); font-weight: 700; }
+h2 { font-family: var(--font-display); font-size: var(--text-2xl); font-weight: 600; }
+h3 { font-family: var(--font-body);    font-size: var(--text-xl);  font-weight: 600; }
+body { font-family: var(--font-body);   font-size: var(--text-base); font-weight: 400; }
+.meta { font-size: var(--text-sm); color: var(--color-text-muted); }
+```
+
+Keep weight range tight: 400 (body), 500/600 (emphasis), 700 (headings). Avoid 900 unless for a single display word.
+
+## Prose Measure
+
+Constrain reading width for paragraphs to **45–75 characters** (`ch`).
+
+```css
+.prose {
+  max-width: 65ch;
+  font-size: var(--text-base);
+  line-height: 1.5;
+}
+```
+
+For multi-column or card text, keep each text block within this measure. Never let body copy stretch across a full 1200px container.
+
+## Ban List
+
+Do **not** use these as an identity or UI font:
+
+- Comic Sans
+- Papyrus
+- Bradley Hand
+- Any `cursive` generic family used as a primary brand font
+- Other "novelty" fonts that undermine legibility
+
+System fallbacks (`system-ui`, `sans-serif`, `serif`, `monospace`) are allowed only as graceful degradation, never as the chosen aesthetic.
+
+## Practical Checklist
+
+- [ ] At most 2 families + 1 mono.
+- [ ] Sizes only from the 8-step scale.
+- [ ] Body line-height 1.5, headings 1.2.
+- [ ] Prose capped at 65ch.
+- [ ] No banned novelty fonts.

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

@@ -1,43 +1,222 @@
----
-name: qk-ui-system-builder
-category: frontend
-version: 7.0.0
-description: "Xây dựng và duy trì Design Systems, Token extraction, và các thư viện UI dùng chung."
----
-
-# qk-ui-system-builder
-
-## Scope
-- Building and maintaining Design Systems and shared UI tokens (Plan & Execute)
-- Enforcing Open Design constraints via `DESIGN.md`
-
-## Verbs
-- `[EXTRACT]`: Read `DESIGN.md` and generate CSS variables/tokens.
-- `[ENFORCE]`: Ensure no generic "AI-slop" tokens are created.
-
-## Constraints
-```yaml
-must:
-  - "Extract reusable design tokens (colors, spacing, typography) from DESIGN.md ONLY"
-  - "Ensure components are accessible (A11y)"
-must_not:
-  - "Create duplicate tokens for the same visual value"
-  - "Invent tokens (e.g., standard Tailwind colors) not explicitly defined in DESIGN.md"
-```
-
-## Policies
-```yaml
-prefer:
-  - Strict adherence to HSL/Oklch over generic HEX colors
-  - Composable components over rigid layouts
-```
-
-## Escalation
-```yaml
-stop:
-  - "DESIGN.md is missing (Prompt user to run bootstrap or provide one)"
-  - "Design tokens conflict with existing DESIGN.md guidelines"
-```
-
-## Output
-- Strict UI component library or Design System tokens mapped to `DESIGN.md`
+---
+name: qk-ui-system-builder
+category: frontend
+version: 7.5.1
+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.1
+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"]
+}
+```
+
+---
+
+
+