@bastani/atomic 0.6.5 → 0.6.6-1

package/.agents/skills/impeccable/reference/onboard.md

@@ -0,0 +1,234 @@
+> **Additional context needed**: the "aha moment" you want users to reach, and users' experience level.
+
+Create or improve onboarding experiences that help users understand, adopt, and succeed with the product quickly.
+
+## Assess Onboarding Needs
+
+Understand what users need to learn and why:
+
+1. **Identify the challenge**:
+   - What are users trying to accomplish?
+   - What's confusing or unclear about current experience?
+   - Where do users get stuck or drop off?
+   - What's the "aha moment" we want users to reach?
+
+2. **Understand the users**:
+   - What's their experience level? (Beginners, power users, mixed?)
+   - What's their motivation? (Excited and exploring? Required by work?)
+   - What's their time commitment? (5 minutes? 30 minutes?)
+   - What alternatives do they know? (Coming from competitor? New to category?)
+
+3. **Define success**:
+   - What's the minimum users need to learn to be successful?
+   - What's the key action we want them to take? (First project? First invite?)
+   - How do we know onboarding worked? (Completion rate? Time to value?)
+
+**CRITICAL**: Onboarding should get users to value as quickly as possible, not teach everything possible.
+
+## Onboarding Principles
+
+Follow these core principles:
+
+### Show, Don't Tell
+- Demonstrate with working examples, not just descriptions
+- Provide real functionality in onboarding, not separate tutorial mode
+- Use progressive disclosure, teach one thing at a time
+
+### Make It Optional (When Possible)
+- Let experienced users skip onboarding
+- Don't block access to product
+- Provide "Skip" or "I'll explore on my own" options
+
+### Time to Value
+- Get users to their "aha moment" ASAP
+- Front-load most important concepts
+- Teach 20% that delivers 80% of value
+- Save advanced features for contextual discovery
+
+### Context Over Ceremony
+- Teach features when users need them, not upfront
+- Empty states are onboarding opportunities
+- Tooltips and hints at point of use
+
+### Respect User Intelligence
+- Don't patronize or over-explain
+- Be concise and clear
+- Assume users can figure out standard patterns
+
+## Design Onboarding Experiences
+
+Create appropriate onboarding for the context:
+
+### Initial Product Onboarding
+
+**Welcome Screen**:
+- Clear value proposition (what is this product?)
+- What users will learn/accomplish
+- Time estimate (honest about commitment)
+- Option to skip (for experienced users)
+
+**Account Setup**:
+- Minimal required information (collect more later)
+- Explain why you're asking for each piece of information
+- Smart defaults where possible
+- Social login when appropriate
+
+**Core Concept Introduction**:
+- Introduce 1-3 core concepts (not everything)
+- Use simple language and examples
+- Interactive when possible (do, don't just read)
+- Progress indication (step 1 of 3)
+
+**First Success**:
+- Guide users to accomplish something real
+- Pre-populated examples or templates
+- Celebrate completion (but don't overdo it)
+- Clear next steps
+
+### Feature Discovery & Adoption
+
+**Empty States**:
+Instead of blank space, show:
+- What will appear here (description + screenshot/illustration)
+- Why it's valuable
+- Clear CTA to create first item
+- Example or template option
+
+Example:
+```
+No projects yet
+Projects help you organize your work and collaborate with your team.
+[Create your first project] or [Start from template]
+```
+
+**Contextual Tooltips**:
+- Appear at relevant moment (first time user sees feature)
+- Point directly at relevant UI element
+- Brief explanation + benefit
+- Dismissable (with "Don't show again" option)
+- Optional "Learn more" link
+
+**Feature Announcements**:
+- Highlight new features when they're released
+- Show what's new and why it matters
+- Let users try immediately
+- Dismissable
+
+**Progressive Onboarding**:
+- Teach features when users encounter them
+- Badges or indicators on new/unused features
+- Unlock complexity gradually (don't show all options immediately)
+
+### Guided Tours & Walkthroughs
+
+**When to use**:
+- Complex interfaces with many features
+- Significant changes to existing product
+- Industry-specific tools needing domain knowledge
+
+**How to design**:
+- Spotlight specific UI elements (dim rest of page)
+- Keep steps short (3-7 steps max per tour)
+- Allow users to click through tour freely
+- Include "Skip tour" option
+- Make replayable (help menu)
+
+**Best practices**:
+- Interactive over passive (let users click real buttons)
+- Focus on workflow, not features ("Create a project" not "This is the project button")
+- Provide sample data so actions work
+
+### Interactive Tutorials
+
+**When to use**:
+- Users need hands-on practice
+- Concepts are complex or unfamiliar
+- High stakes (better to practice in safe environment)
+
+**How to design**:
+- Sandbox environment with sample data
+- Clear objectives ("Create a chart showing sales by region")
+- Step-by-step guidance
+- Validation (confirm they did it right)
+- Graduation moment (you're ready!)
+
+### Documentation & Help
+
+**In-product help**:
+- Contextual help links throughout interface
+- Keyboard shortcut reference
+- Search-able help center
+- Video tutorials for complex workflows
+
+**Help patterns**:
+- `?` icon near complex features
+- "Learn more" links in tooltips
+- Keyboard shortcut hints (`⌘K` shown on search box)
+
+## Empty State Design
+
+Every empty state needs:
+
+### What Will Be Here
+"Your recent projects will appear here"
+
+### Why It Matters
+"Projects help you organize your work and collaborate with your team"
+
+### How to Get Started
+[Create project] or [Import from template]
+
+### Visual Interest
+Illustration or icon (not just text on blank page)
+
+### Contextual Help
+"Need help getting started? [Watch 2-min tutorial]"
+
+**Empty state types**:
+- **First use**: Never used this feature (emphasize value, provide template)
+- **User cleared**: Intentionally deleted everything (light touch, easy to recreate)
+- **No results**: Search or filter returned nothing (suggest different query, clear filters)
+- **No permissions**: Can't access (explain why, how to get access)
+- **Error state**: Failed to load (explain what happened, retry option)
+
+## Implementation Patterns
+
+### Technical approaches:
+
+**Tooltip libraries**: Tippy.js, Popper.js
+**Tour libraries**: Intro.js, Shepherd.js, React Joyride
+**Modal patterns**: Focus trap, backdrop, ESC to close
+**Progress tracking**: LocalStorage for "seen" states
+**Analytics**: Track completion, drop-off points
+
+**Storage patterns**:
+```javascript
+// Track which onboarding steps user has seen
+localStorage.setItem('onboarding-completed', 'true');
+localStorage.setItem('feature-tooltip-seen-reports', 'true');
+```
+
+**IMPORTANT**: Don't show same onboarding twice (annoying). Track completion and respect dismissals.
+
+**NEVER**:
+- Force users through long onboarding before they can use product
+- Patronize users with obvious explanations
+- Show same tooltip repeatedly (respect dismissals)
+- Block all UI during tour (let users explore)
+- Create separate tutorial mode disconnected from real product
+- Overwhelm with information upfront (progressive disclosure!)
+- Hide "Skip" or make it hard to find
+- Forget about returning users (don't show initial onboarding again)
+
+## Verify Onboarding Quality
+
+Test with real users:
+
+- **Time to completion**: Can users complete onboarding quickly?
+- **Comprehension**: Do users understand after completing?
+- **Action**: Do users take desired next step?
+- **Skip rate**: Are too many users skipping? (Maybe it's too long or not valuable)
+- **Completion rate**: Are users completing? (If low, simplify)
+- **Time to value**: How long until users get first value?
+
+Remember: You're a product educator with excellent teaching instincts. Get users to their "aha moment" as quickly as possible. Teach the essential, make it contextual, respect user time and intelligence.

package/.agents/skills/{optimize/SKILL.md → impeccable/reference/optimize.md}

@@ -1,11 +1,3 @@
----
-name: optimize
-description: Diagnoses and fixes UI performance across loading speed, rendering, animations, images, and bundle size. Use when the user mentions slow, laggy, janky, performance, bundle size, load time, or wants a faster, smoother experience.
-version: 2.1.1
-user-invocable: true
-argument-hint: "[target]"
----
-
 Identify and fix performance issues to create faster, smoother user experiences.
 
 ## Assess Performance Issues
@@ -117,10 +109,10 @@ elements.forEach((el, i) => {
 - Virtual scrolling for very long lists (react-window, react-virtualized)
 
 **Reduce Paint & Composite**:
-- Use `transform` and `opacity` for animations (GPU-accelerated)
-- Avoid animating layout properties (width, height, top, left)
+- Use `transform` and `opacity` for reliable movement, but allow blur, filters, masks, clip paths, shadows, and color shifts when they create meaningful polish
+- Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
 - Use `will-change` sparingly for known expensive operations
-- Minimize paint areas (smaller is faster)
+- Bound expensive paint areas for blur/filter/shadow effects (smaller and isolated is faster)
 
 ### Animation Performance
 
@@ -263,4 +255,4 @@ Test that optimizations worked:
 - **No regressions**: Ensure functionality still works
 - **User perception**: Does it *feel* faster?
 
-Remember: Performance is a feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance.
+Remember: Performance is a feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance.

package/.agents/skills/{overdrive/SKILL.md → impeccable/reference/overdrive.md}

@@ -1,11 +1,3 @@
----
-name: overdrive
-description: Pushes interfaces past conventional limits with technically ambitious implementations — shaders, spring physics, scroll-driven reveals, 60fps animations. Use when the user wants to wow, impress, go all-out, or make something that feels extraordinary.
-version: 2.1.1
-user-invocable: true
-argument-hint: "[target]"
----
-
 Start your response with:
 
 ```
@@ -13,27 +5,23 @@ Start your response with:
 》》》 Entering overdrive mode...
 ```
 
-Push an interface past conventional limits. This isn't just about visual effects — it's about using the full power of the browser to make any part of an interface feel extraordinary: a table that handles a million rows, a dialog that morphs from its trigger, a form that validates in real-time with streaming feedback, a page transition that feels cinematic.
-
-## MANDATORY PREPARATION
-
-Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first.
+Push an interface past conventional limits. This isn't just about visual effects. It's about using the full power of the browser to make any part of an interface feel extraordinary: a table that handles a million rows, a dialog that morphs from its trigger, a form that validates in real-time with streaming feedback, a page transition that feels cinematic.
 
-**EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate.
+**EXTRA IMPORTANT FOR THIS COMMAND**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate.
 
 ### Propose Before Building
 
-This skill has the highest potential to misfire. Do NOT jump straight into implementation. You MUST:
+This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST:
 
-1. **Think through 2-3 different directions** — consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like.
-2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity).
+1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like.
+2. **STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity).
 3. Only proceed with the direction the user confirms.
 
 Skipping this step risks building something embarrassing that needs to be thrown away.
 
 ### Iterate with Browser Automation
 
-Technically ambitious effects almost never work on the first try. You MUST actively use browser automation tools to preview your work, visually verify the result, and iterate. Do not assume the effect looks right — check it. Expect multiple rounds of refinement. The gap between "technically works" and "looks extraordinary" is closed through visual iteration, not code alone.
+Technically ambitious effects almost never work on the first try. You MUST actively use browser automation tools to preview your work, visually verify the result, and iterate. Do not assume the effect looks right, check it. Expect multiple rounds of refinement. The gap between "technically works" and "looks extraordinary" is closed through visual iteration, not code alone.
 
 ---
 
@@ -91,7 +79,7 @@ Organized by what you're trying to achieve, not by technology name.
 - **Web Audio API** — spatial audio, audio-reactive visualizations, sonic feedback. Requires user gesture to start.
 - **Device APIs** — orientation, ambient light, geolocation. Use sparingly and always with user permission.
 
-**NOTE**: This skill is about enhancing how an interface FEELS, not changing what a product DOES. Adding real-time collaboration, offline support, or new backend capabilities are product decisions, not UI enhancements. Focus on making existing features feel extraordinary.
+**NOTE**: This command is about enhancing how an interface FEELS, not changing what a product DOES. Adding real-time collaboration, offline support, or new backend capabilities are product decisions, not UI enhancements. Focus on making existing features feel extraordinary.
 
 ## Implement with Discipline
 
@@ -128,7 +116,7 @@ The gap between "cool" and "extraordinary" is in the last 20% of refinement: the
 - Ship effects that cause jank on mid-range devices
 - Use bleeding-edge APIs without a functional fallback
 - Add sound without explicit user opt-in
-- Use technical ambition to mask weak design fundamentals — fix those first with other skills
+- Use technical ambition to mask weak design fundamentals; fix those first with other commands
 - Layer multiple competing extraordinary moments — focus creates impact, excess creates noise
 
 ## Verify the Result
@@ -139,4 +127,4 @@ The gap between "cool" and "extraordinary" is in the last 20% of refinement: the
 - **The accessibility test**: Enable reduced motion. Still beautiful?
 - **The context test**: Does this make sense for THIS brand and audience?
 
-Remember: "Technically extraordinary" isn't about using the newest API. It's about making an interface do something users didn't think a website could do.
+Remember: "Technically extraordinary" isn't about using the newest API. It's about making an interface do something users didn't think a website could do.

package/.agents/skills/{critique → impeccable}/reference/personas.md

@@ -159,7 +159,7 @@ Choose personas based on the interface type:
 
 ## Project-Specific Personas
 
-If `.github/copilot-instructions.md` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information:
+If `AGENTS.md` contains a `## Design Context` section (generated by `impeccable teach`), derive 1–2 additional personas from the audience and brand information:
 
 1. Read the target audience description
 2. Identify the primary user archetype not covered by the 5 predefined personas

package/.agents/skills/{polish/SKILL.md → impeccable/reference/polish.md}

@@ -1,32 +1,20 @@
----
-name: polish
-description: Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when the user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great.
-version: 2.1.1
-user-invocable: true
-argument-hint: "[target]"
----
-
-## MANDATORY PREPARATION
-
-Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: quality bar (MVP vs flagship).
-
----
+> **Additional context needed**: quality bar (MVP vs flagship).
 
 Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.
 
 ## Design System Discovery
 
-Before polishing, understand the system you are polishing toward:
+Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work.
 
-1. **Find the design system**: Search for design system documentation, component libraries, style guides, or token definitions. Study the core patterns: color tokens, spacing scale, typography styles, component API.
-2. **Note the conventions**: How are shared components imported? What spacing scale is used? Which colors come from tokens vs hard-coded values? What motion and interaction patterns are established?
-3. **Identify drift**: Where does the target feature deviate from the system? Hard-coded values that should be tokens, custom components that duplicate shared ones, spacing that doesn't match the scale.
+1. **Find the design system**: Search for design system documentation, component libraries, style guides, or token definitions. Study the core patterns: design principles, target audience, color tokens, spacing scale, typography styles, component API, motion conventions.
+2. **Note the conventions**: How are shared components imported? What spacing scale is used? Which colors come from tokens vs hard-coded values? What motion and interaction patterns are established? What flow shapes are used for comparable actions (modal vs full-page, inline vs route, save-on-blur vs explicit submit)?
+3. **Identify drift, then name the root cause**: For every deviation, classify it as a **missing token** (the value should exist in the system but doesn't), a **one-off implementation** (a shared component already exists but wasn't used), or a **conceptual misalignment** (the feature's flow, IA, or hierarchy doesn't match neighboring features). The fix differs by category — patch the value, swap to the shared component, or rework the flow. Fixing the symptom without naming the cause is how drift compounds.
 
-If a design system exists, polish should align the feature with it. If none exists, polish against the conventions visible in the codebase.
+If a design system exists, polish **must** align the feature with it. If none exists, polish against the conventions visible in the codebase. **If anything about the system is ambiguous, ask — never guess at design system principles.**
 
 ## Pre-Polish Assessment
 
-Understand the current state and goals:
+Understand the current state and goals before touching anything:
 
 1. **Review completeness**:
    - Is it functionally complete?
@@ -34,13 +22,18 @@ Understand the current state and goals:
    - What's the quality bar? (MVP vs flagship feature?)
    - When does it ship? (How much time for polish?)
 
-2. **Identify polish areas**:
+2. **Think experience-first**: Who actually uses this, and what's the best possible experience for them? Effective design beats decorative polish — a feature that looks beautiful but fights the user's flow is not polished. Walk the path from their perspective before opening DevTools.
+
+3. **Identify polish areas**:
    - Visual inconsistencies
    - Spacing and alignment issues
    - Interaction state gaps
    - Copy inconsistencies
    - Edge cases and error states
    - Loading and transition smoothness
+   - Information architecture and flow drift (does this feature reveal complexity the way neighboring features do?)
+
+4. **Triage cosmetic vs functional**: Classify each issue as **cosmetic** (looks off, doesn't impede the user) or **functional** (breaks, blocks, or confuses the experience). When polish time is tight, functional issues ship first; cosmetic ones can land in a follow-up. Quality should be consistent — never perfect one corner while leaving another rough.
 
 **CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.
 
@@ -62,6 +55,16 @@ Work through these dimensions methodically:
 - Test at multiple viewport sizes
 - Look for elements that "feel" off
 
+### Information Architecture & Flow
+
+Visual polish on a misshapen flow is wasted work. Match the *shape* of the experience to the system, not just the surface.
+
+- **Progressive disclosure**: Match how much is revealed when, compared to neighboring features. A settings page exposing 40 fields when the rest of the app reveals 5 at a time is drift, even if every field is perfectly styled.
+- **Established user flows**: Multi-step actions follow the same shape as comparable flows elsewhere — modal vs full-page, inline edit vs separate route, save-on-blur vs explicit submit, optimistic vs pessimistic updates.
+- **Hierarchy & complexity**: The same conceptual weight gets the same visual weight throughout. Primary actions don't become tertiary in one corner of the product, and tertiary actions don't shout.
+- **Empty, loading, and arrival transitions**: How content arrives, updates, and leaves matches how it does in adjacent features.
+- **Naming and mental model**: The feature uses the same nouns and verbs as the rest of the system. A "Workspace" here shouldn't be a "Project" three screens away.
+
 ### Typography Refinement
 
 - **Hierarchy consistency**: Same elements use same sizes/weights throughout
@@ -101,7 +104,7 @@ Every interactive element needs all states:
 
 - **Smooth transitions**: All state changes animated appropriately (150-300ms)
 - **Consistent easing**: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic—they feel dated.
-- **No jank**: 60fps animations, only animate transform and opacity
+- **No jank**: Smooth animations; use atmospheric blur/filter/mask/shadow effects when they add polish, but bound expensive paint areas and avoid casual layout-property animation
 - **Appropriate motion**: Motion serves purpose, not decoration
 - **Reduced motion**: Respects `prefers-reduced-motion`
 
@@ -170,6 +173,8 @@ Every interactive element needs all states:
 
 Go through systematically:
 
+- [ ] Aligned to the design system (drift named and resolved by root cause)
+- [ ] Information architecture and flow shape match neighboring features
 - [ ] Visual alignment perfect at all breakpoints
 - [ ] Spacing uses design tokens consistently
 - [ ] Typography hierarchy consistent
@@ -195,12 +200,15 @@ Go through systematically:
 
 **NEVER**:
 - Polish before it's functionally complete
+- Polish without aligning to the design system — that's decoration on drift
+- Guess at design system principles instead of asking when something is ambiguous
 - Spend hours on polish if it ships in 30 minutes (triage)
 - Introduce bugs while polishing (test thoroughly)
-- Ignore systematic issues (if spacing is off everywhere, fix the system)
+- Ignore systematic issues (if spacing is off everywhere, fix the system, not just one screen)
 - Perfect one thing while leaving others rough (consistent quality level)
 - Create new one-off components when design system equivalents exist
 - Hard-code values that should use design tokens
+- Introduce new patterns or flows that diverge from established ones
 
 ## Final Verification
 
@@ -221,4 +229,4 @@ After polishing, ensure code quality:
 - **Consolidate tokens**: If you introduced new values, check whether they should be tokens.
 - **Verify DRYness**: Look for duplication introduced during polishing and consolidate.
 
-Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details - they matter.
+Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details - they matter.

package/.agents/skills/impeccable/reference/product.md

@@ -0,0 +1,62 @@
+# Product register
+
+When design SERVES the product: app UIs, admin dashboards, settings panels, data tables, tools, authenticated surfaces, anything where the user is in a task.
+
+## The product slop test
+
+Not "would someone say AI made this" — familiarity is often a feature here. The test is: would a user fluent in the category's best tools (Linear, Figma, Notion, Raycast, Stripe come to mind) sit down and trust this interface, or pause at every subtly-off component?
+
+Product UI's failure mode isn't flatness, it's strangeness without purpose: over-decorated buttons, mismatched form controls, gratuitous motion, display fonts where labels should be, invented affordances for standard tasks. The bar is earned familiarity. The tool should disappear into the task.
+
+## Typography
+
+- **System fonts are legitimate.** `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif` gives you native feel on every platform. Inter is the common cross-platform default for a reason.
+- **One family is often right.** Product UIs don't need display/body pairing. A well-tuned sans carries headings, buttons, labels, body, data.
+- **Fixed rem scale, not fluid.** Clamp-sized headings don't serve product UI. Users view at consistent DPI, and a fluid h1 that shrinks in a sidebar looks worse, not better.
+- **Tighter scale ratio.** 1.125–1.2 between steps is typical. More type elements here than on brand surfaces; exaggerated contrast creates noise.
+- **Line length still applies for prose** (65–75ch). Data and compact UI can run denser — tables at 120ch+ are fine.
+
+## Color
+
+Product defaults to Restrained. A single surface can earn Committed — a dashboard where one category color carries a report, an onboarding flow with a drenched welcome screen — but Restrained is the floor.
+
+- State-rich semantic vocabulary: hover, focus, active, disabled, selected, loading, error, warning, success, info. Standardize these.
+- Accent color used for primary actions, current selection, and state indicators only — not decoration.
+- A second neutral layer for sidebars, toolbars, and panels (slightly cooler or warmer than the content surface).
+
+## Layout
+
+- Predictable grids. Consistency IS an affordance — users navigate faster when the structure is expected.
+- Familiar patterns are features. Standard navigation (top bar, side nav), breadcrumbs, tabs, and form layouts have established user expectations. Don't reinvent for flavor.
+- Responsive behavior is structural (collapse sidebar, responsive table, breakpoint-driven columns), not fluid typography.
+
+## Components
+
+Every interactive component has: default, hover, focus, active, disabled, loading, error. Don't ship with half of these.
+
+- Skeleton states for loading, not spinners in the middle of content.
+- Empty states that teach the interface, not "nothing here."
+- Consistent affordances across the surface. Same button shape. Same form-control vocabulary. Same icon style.
+
+## Motion
+
+- 150–250 ms on most transitions. Users are in flow — don't make them wait for choreography.
+- Motion conveys state, not decoration. State change, feedback, loading, reveal — nothing else.
+- No orchestrated page-load sequences. Product loads into a task; users don't want to watch it load.
+
+## Product bans (on top of the shared absolute bans)
+
+- Decorative motion that doesn't convey state.
+- Inconsistent component vocabulary across screens. If the "save" button looks different in two places, one is wrong.
+- Display fonts in UI labels, buttons, data.
+- Reinventing standard affordances for flavor (custom scrollbars, weird form controls, non-standard modals).
+- Heavy color or full-saturation accents on inactive states.
+
+## Product permissions
+
+Product can afford things brand surfaces can't.
+
+- System fonts and familiar sans defaults (Inter, SF Pro, system-ui stacks).
+- Standard navigation patterns: top bar + side nav, breadcrumbs, tabs, command palettes.
+- Density. Tables with many rows, panels with many labels, dense information when users need it.
+- Consistency over surprise. The same visual vocabulary screen to screen is a virtue; delight is saved for moments, not pages.

package/.agents/skills/{quieter/SKILL.md → impeccable/reference/quieter.md}

@@ -1,16 +1,12 @@
----
-name: quieter
-description: Tones down visually aggressive or overstimulating designs, reducing intensity while preserving quality. Use when the user mentions too bold, too loud, overwhelming, aggressive, garish, or wants a calmer, more refined aesthetic.
-version: 2.1.1
-user-invocable: true
-argument-hint: "[target]"
+Reduce visual intensity in designs that are too bold, aggressive, or overstimulating, creating a more refined and approachable aesthetic without losing effectiveness.
+
 ---
 
-Reduce visual intensity in designs that are too bold, aggressive, or overstimulating, creating a more refined and approachable aesthetic without losing effectiveness.
+## Register
 
-## MANDATORY PREPARATION
+Brand: "quieter" means more restrained palette, more whitespace, more typographic air. Drama is reduced, not eliminated — the POV stays intact.
 
-Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first.
+Product: "quieter" means reducing visual noise — fewer background accents, flatter cards, less color, less motion. The tool should disappear more completely into the task.
 
 ---
 
@@ -32,7 +28,7 @@ Analyze what makes the design feel too intense:
    - What's working? (Don't throw away good ideas)
    - What's the core message? (Preserve what matters)
 
-If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
+If any of these are unclear from the codebase, STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer.
 
 **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined, sophisticated, and easier on the eyes. Think luxury, not laziness.
 
@@ -100,4 +96,4 @@ Ensure refinement maintains quality:
 - **Better reading**: Is text easier to read for extended periods?
 - **Sophistication**: Does it feel more refined and premium?
 
-Remember: Quiet design is confident design. It doesn't need to shout. Less is more, but less is also harder. Refine with precision and maintain intentionality.
+Remember: Quiet design is confident design. It doesn't need to shout. Less is more, but less is also harder. Refine with precision and maintain intentionality.