TypeUI Design Fundamentals
Design-system-agnostic UI/UX principles for AI-generated interfaces, resolving decisions your design system doesn't cover and aesthetic-versus-accessibility conflicts.
Universal UI/UX design-principle reference (visual hierarchy, interaction laws, typography foundations, WCAG accessibility) — design-system-agnostic, purely knowledge-based guidance with no remote service, smaller risk surface than the other platform-adapter skills in this repo.
What does this skill do, and when should you use it?
typeui-fundamentals is one skill inside the TypeUI monorepo, living at skills/fundamentals/ in the bergside/typeui repository. It ships five principle modules covering visual hierarchy, spacing, interaction and UX laws, typography, and WCAG 2.1/2.2 accessibility. The principles are timeless and bind to no design system; they are meant to load after your design system so the agent understands why token decisions are correct. An explicit conflict hierarchy is declared: design systems win on concrete values, these fundamentals win on structural principles, the vertical layer wins on process, and accessibility overrides aesthetic preferences at every level.
The skill is a set of Markdown reference files: ui-principles.md (hierarchy, layout rhythm, color theory, depth, responsive adaptation), spacing-principles.md (4-point grid, spacing tiers), ux-principles.md (30 UX laws, 9 control states, touch targets, cognitive load), typography-principles.md (type scales, readability, responsive type, brand tone), and accessibility.md (contrast, focus visibility, keyboard navigation, motion safety, ARIA). Once loaded, the agent applies these principles to any decision the design system's tokens don't cover, and flags — rather than silently breaks — conflicts with the design system. It deliberately does not define workflow phases, quality gates, anti-pattern catalogs, or design tokens; those live in sibling skills.
- A full-stack or frontend developer generating UI with Claude Code or Codex in a project that has no established design system yet and wants principled defaults instead of improvised choices.
- A team already using a TypeUI design-system skill wants the agent to explain the reasoning behind token-based decisions when writing or refactoring UI.
- A reviewer or audit agent needs to validate generated screens against WCAG requirements such as contrast ratios, focus visibility, and keyboard navigation.
- A situation where aesthetics conflict with accessibility: this skill enforces the rule that accessibility wins.
- Multi-framework projects with no framework-specific system, needing baseline principles that apply to every surface regardless of vertical or workflow phase.
What are this skill's strengths and limitations?
- Design-system-agnostic — works with any frontend stack and any surface.
- Broad coverage in five modules: hierarchy, spacing, UX laws, typography, WCAG accessibility.
- Explicit conflict-resolution hierarchy prevents principles and design systems from contradicting each other silently.
- SKILL.md is MIT-licensed with author metadata (typeui.sh).
- Composes in layers with sibling TypeUI skills (design system, vertical workflows).
- Delivers most value alongside a design system; standalone it provides no concrete tokens or component specs.
- The repo's GitHub license is NOASSERTION overall; only SKILL.md and the CLI claim MIT, so verify before redistributing.
- No test suite or evaluation evidence for the principle content (30 UX laws, 9-state contracts, etc.).
- Per-client install paths and trigger examples are not documented in the source.
- Workflows, quality gates, anti-patterns, and industry content live in sibling skills and require separate installation.
How do you install this skill?
Run in your terminal: npx skills add https://github.com/bergside/typeui --skill typeui-fundamentals. Alternatively, copy the skills/fundamentals/ directory from github.com/bergside/typeui into your Agent Skills folder manually. The source does not document default skill directories per client; consult your tool's own docs for placement.
How do you use this skill?
Follow the documented load order: load your design system first (SKILL.md / DESIGN.md plus token modules), then this skill's five principle files. Then request UI work normally, e.g. "Build a settings page with this design system and make sure it meets WCAG contrast requirements." When the design system is silent on a decision, the agent falls back to these principles and flags any conflicts for review. The CLI is for installation/generation only; the skill itself has no runtime commands.