Frontend Guidelines (reference)

The full guideline inventory for a frontend module — what the refresh skills produce under overview/, how the frontend agents consume it, and the project-style-guide mechanism that lets you shape the auto-generated content. For the overview, the override levers, and the content principles, see Project Guidelines.

Frontend guidelines live per module at:

.swifter/specs/{module}/overview/

They are generated by two skills the frontend analyst runs — you don't author them from scratch.

The file set

refresh-framework-knowledge (which reads package.json and researches the official framework docs) writes a 9-file split:

File	Role
framework_knowledge.md	Entry point — written last, indexes all the others
STACK.md	Framework, version, dependencies, build/test/lint commands
STRUCTURE.md	Directory layout, file naming, component selectors
ARCHITECTURE.md	Component patterns, state management, routing, data flow
CONVENTIONS.md	Code style, imports/exports, path aliases, styling, TypeScript
TESTING.md	Test framework, patterns, mocking
INTEGRATIONS.md	External-library patterns, auth, telemetry
CONCERNS.md	Forbidden/restricted tech, deprecated patterns, tech debt
TEMPLATES.md	Complete compilable code templates

refresh-storybook-knowledge writes one more file alongside them:

File	Role
storybook_knowledge.md	Storybook conventions and story templates

How the agents read it

The frontend agents (swifter-frontend-analyst, swifter-frontend-developer) enter through the framework_knowledge.md entry point and follow its index to the detail files they need (patterns, conventions, templates). They don't open STACK.md / CONVENTIONS.md / etc. by name — the entry point is the index that points to them.

framework_knowledge.md and storybook_knowledge.md are both prerequisites for generate-component: if either is missing, the command stops (missing_framework_knowledge / missing_storybook_knowledge) and runs the matching refresh skill before continuing.

Shaping the generated content — the style-guide lever

Because these files are auto-generated, hand-edits are regenerated away on the next refresh. The durable lever is that refresh-framework-knowledge scans project markdown as research input. Its <research_sources> block reads, in priority order:

1. .swifter/specs/{module}/overview/*.md — excluding the generated overview files
2. **/*.md project files — excluding node_modules, dist

…and the skill is explicit that project conventions override framework defaults when a style guide is present. It also runs a verification check that any project style guide was "discovered and attributed (or absence confirmed)".

How to use it:

1. Put a markdown style guide at the project root — e.g. STYLE_GUIDE.md.
2. Give it headings that mirror the knowledge files (CONVENTIONS, STRUCTURE, INTEGRATIONS, CONCERNS, …), so the skill maps each input section to the right output file.
3. Re-run refresh-framework-knowledge. Your rules are folded into the generated CONVENTIONS.md / STRUCTURE.md / etc., overriding framework defaults.

The scan is markdown-only. Conventions that live solely in .eslintrc, .prettierrc, .editorconfig, or IDE settings are not picked up — only what you write in markdown reaches the knowledge layer. If your real conventions live in tool configs, restate the relevant ones in your style guide.

When to refresh

Skill	Re-run when
refresh-framework-knowledge	The framework or a major dependency changes (package.json changes meaningfully), the overview is missing, or a monolithic framework_knowledge.md needs splitting. Preserves existing valid content and migrates a monolith into the split.
refresh-storybook-knowledge	Storybook or its addons change.