Frontend System

🎨 Frontend & Design System

1. Internationalization (I18n)

> [!CAUTION] > ZERO HARDCODED STRINGS! > Every user-visible text must use the useTranslation hook / t() (or your project's i18n equivalent).

Required languages: define the project's locale list in your i18n config (e.g. pl.json, en.json, ...).

Key structure:

{
  "component.action.state": "Text"
}

3. Styling

• Framework: Tailwind CSS
• Animations: Framer Motion (for UI interactions) or CSS Transitions
• Responsiveness: Mobile-first (sm:, md:, lg:)
• Dark mode: Supported via dark: classes

4. SEO

New public pages MUST include the `` component:

5. Accessibility (a11y)

• Use semantic HTML (`, , `)
• All interactive elements must have aria-label or visible text
• Colors: minimum 4.5:1 contrast ratio (WCAG AA)

6. Pitfalls (Lessons Learned)

P1. Runtime fetch of static files

Mistake: Files fetched via fetch() at runtime (not imported) reside outside public/ → they don't end up in dist/. Fix: Runtime files MUST be in public/. Only public/ is copied to the build output.

P2. Config defensiveness

Mistake: Missing field in a JSON config (e.g., xRange) → TypeError crash in the renderer. Fix: Always use optional chaining with defaults: config?.xRange ?? [-5, 5].

P3. useIsMobile — matchMedia vs resize

Mistake: addEventListener('resize') + innerWidth — less performant and off-by-one at the breakpoint. Fix: matchMedia('(max-width: ${breakpoint - 1}px)') — performant, no overlap.

P4. PWA cache — large chunks

Mistake: Default workbox maximumFileSizeToCacheInBytes limit (2MB) silently skips large chunks. Fix: Increase the limit when the bundle grows. Without this, offline mode loses critical resources.

P5. Ratings / nullable values: null vs 0

Mistake: Missing rating mapped as ?? 0 → renders 0 stars (grey), as if someone rated it 0. Fix: Use ?? undefined — triggers the "no rating" state (yellow default).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ZroZoom
• Source: ZroZoom/agent-skills-core
• License: MIT

Install and usage instructions live in the source repository linked above.