teach-impeccable
Verifiedby pbakaus · Updated Apr 16, 2026
One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines.
See It In Action
Okay, I've read through every file. Here's my review and the one question I need answered before finalizing.
Design Review Summary
What's already solid
- Token system — semantic color names, spacing scale, dark-mode overrides, and
prefers-reduced-motionblanket are all in place. - Semantic HTML —
main,header,section[aria-label],article[aria-label]on KPI cards. Good structure. - KpiCard — trend symbols are
aria-hidden, text labels carry meaning. No color-only information. All styling uses tokens. - Accessibility guidelines doc — covers WCAG AA, focus indicators, color independence, motion budget, minimum font sizes.
Issues found
| # | File | Issue | Severity |
|---|---|---|---|
| 1 | App.tsx:59 | Button text color hardcoded #fff — violates CLAUDE.md ("no hardcoded brand colors in components") | Style drift |
| 2 | App.tsx:60 | Button padding 10px 14px uses raw px instead of space tokens | Style drift |
| 3 | App.tsx:53-64 | No focus-visible style on button — inline styles can't set :focus-visible, so keyboard users get no visible focus ring. Violates WCAG 2.4.7 and the accessibility guidelines doc. | A11y blocker |
| 4 | tokens.css | No --color-text-inverse token for white-on-brand surfaces | Gap |
| 5 | CLAUDE.md | No guidance on interactive states (focus, hover, active, disabled) | Gap |
| 6 | CLAUDE.md | No guidance on when to use CSS files vs inline styles (current inline-only pattern blocks pseudo-class a11y) | Gap |
The one question I need from you
Issue #3 is the big one. The entire codebase uses inline styles, which makes it impossible to style :focus-visible. To fix the button (and any future interactive elements), we need either:
- (A) A small global CSS rule for interactive focus (e.g.,
button:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 2px; }) added totokens.cssor a new base stylesheet, or - (B) Move component styles to CSS modules so pseudo-classes work per-component.
Which approach do you prefer — (A) global focus baseline, or (B) CSS modules? Everything else I can lock down now.
While you think about that, I'll go ahead and make the non-controversial fixes and update the design context:
Now update the CLAUDE.md with the locked-down guidance:
Let me verify everything looks right:
Everything's clean. Here's the full summary of what was done and what's still open:
✅ Changes made
src/styles/tokens.css
- Added
--color-text-inverse: #fffffftoken for white-on-brand text
src/App.tsx
- Replaced hardcoded
#fff→var(--color-text-inverse)on the button - Replaced raw
10px 14pxpadding →var(--space-3) var(--space-4)spacing tokens
CLAUDE.md — significantly expanded with three new sections:
- UI style baseline — typography, color, radius, elevation, and motion rules codified from what's already in the codebase
- Accessibility requirements — focus-visible mandate, color independence, semantic HTML, aria-live, and the inline-style pseudo-class limitation called out explicitly
- Expanded engineering guardrails —
--color-text-inverserule, spacing token rule - Expanded handoff expectations — dark-mode counterpart requirement for new tokens
🔴 Still open — needs your call
The button has no :focus-visible outline. Keyboard users currently get no visible focus indicator, which is a WCAG 2.4.7 failure. I've documented the requirement in CLAUDE.md but haven't picked an implementation because it's an architectural choice:
- (A) Global focus baseline in
tokens.css— one rule likebutton:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 2px; }. Minimal, stable, covers all buttons immediately. - (B) CSS modules — more flexible per-component, but bigger migration from the current all-inline approach.
Which way do you want to go? Once you pick, I can implement it and this dashboard will be fully locked down.
Re: syncing — yes, I'd recommend committing these changes. The CLAUDE.md updates ensure any future AI or human edits stay inside the guardrails we just defined. Want me to create the commit?
Permissions
| Scope | Description |
|---|---|
| filesystem:read | |
| filesystem:write |
SKILL.md
Gather design context for this project, then persist it for all future sessions.
Step 1: Explore the Codebase
Before asking questions, thoroughly scan the project to discover what you can:
- README and docs: Project purpose, target audience, any stated goals
- Package.json / config files: Tech stack, dependencies, existing design libraries
- Existing components: Current design patterns, spacing, typography in use
- Brand assets: Logos, favicons, color values already defined
- Design tokens / CSS variables: Existing color palettes, font stacks, spacing scales
- Any style guides or brand documentation
Note what you've learned and what remains unclear.
Step 2: Ask UX-Focused Questions
STOP and call the AskUserQuestion tool to clarify. Focus only on what you couldn't infer from the codebase:
Users & Purpose
- Who uses this? What's their context when using it?
- What job are they trying to get done?
- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.)
Brand & Personality
- How would you describe the brand personality in 3 words?
- Any reference sites or apps that capture the right feel? What specifically about them?
- What should this explicitly NOT look like? Any anti-references?
Aesthetic Preferences
- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
- Light mode, dark mode, or both?
- Any colors that must be used or avoided?
Accessibility & Inclusion
- Specific accessibility requirements? (WCAG level, known user needs)
- Considerations for reduced motion, color blindness, or other accommodations?
Skip questions where the answer is already clear from the codebase exploration.
Step 3: Write Design Context
Synthesize your findings and the user's answers into a ## Design Context section:
## Design Context
### Users
[Who they are, their context, the job to be done]
### Brand Personality
[Voice, tone, 3-word personality, emotional goals]
### Aesthetic Direction
[Visual tone, references, anti-references, theme]
### Design Principles
[3-5 principles derived from the conversation that should guide all design decisions]
Write this section to .impeccable.md in the project root. If the file already exists, update the Design Context section in place.
Then STOP and call the AskUserQuestion tool to clarify. whether they'd also like the Design Context appended to CLAUDE.md. If yes, append or update the section there as well.
Confirm completion and summarize the key design principles that will now guide all future work.
FAQ
What does teach-impeccable do?
One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines.
When should I use teach-impeccable?
Use it when you need a repeatable workflow that produces code diff.
What does teach-impeccable output?
In the evaluated run it produced code diff.
How do I install or invoke teach-impeccable?
Ask the agent to use this skill when the task matches its documented workflow.
Which agents does teach-impeccable support?
Agent support is inferred from the source, but not explicitly declared.
What tools, channels, or permissions does teach-impeccable need?
It uses no extra tools; channels commonly include diff; permissions include filesystem:read, filesystem:write.
Is teach-impeccable safe to install?
Static analysis marked this skill as medium risk; review side effects and permissions before enabling it.
How is teach-impeccable different from an MCP or plugin?
A skill packages instructions and workflow conventions; tools, MCP servers, and plugins are dependencies the skill may call during execution.
Does teach-impeccable outperform not using a skill?
About teach-impeccable
When to use teach-impeccable
At the start of a project to capture design intent for future AI-assisted work. When a codebase has incomplete or implicit design conventions that need to be documented. When you want persistent design guidance stored in project files like .impeccable.md or CLAUDE.md.
When teach-impeccable is not the right choice
When you need actual UI implementation or visual mockups rather than design-context documentation. When the project should remain read-only and no files should be modified.
What it produces
Produces code diff.