typeui-fundamentals
bergside/typeui
Universal UI/UX design principles for visual hierarchy, typography, interaction, and WCAG accessibility across any design system.
What is typeui-fundamentals?
A design-system-agnostic reference covering visual hierarchy, interaction laws, typography foundations, and WCAG 2.1/2.2 accessibility requirements. Use it to make design decisions not covered by your specific design system, validate principle compliance, and resolve conflicts between aesthetics and accessibility.
- Defines universal visual design principles including hierarchy, layout rhythm, color theory, depth, and responsive adaptation
- Covers spacing-specific principles: 4-point grid, proximity grouping, vertical/horizontal rhythm, and component spacing tiers
- Explains 30 UX laws, control state contracts, hover/active techniques, touch targets, and feedback loops
- Provides typography foundations: type system scales, modular ratios, readability measures, and responsive type rules
- Details WCAG 2.1/2.2 compliance requirements: contrast ratios, focus visibility, keyboard navigation, motion safety, and semantic structure
How to install typeui-fundamentals
npx skills add https://github.com/bergside/typeui --skill typeui-fundamentalsHow to use typeui-fundamentals
- 1.Load this skill after your design system's SKILL.md and token modules
- 2.Reference ui-principles.md for visual hierarchy, layout, color, and component behavior decisions
- 3.Consult spacing-principles.md when determining gaps between elements and section spacing tiers
- 4.Check ux-principles.md for interaction states, control contracts, and UX law application
- 5.Use typography-principles.md to validate type scales, readability, and responsive sizing
- 6.Review accessibility.md to verify WCAG 2.1/2.2 compliance for contrast, focus, keyboard nav, and semantic structure
- 7.When design system and principles conflict, the design system wins; flag conflicts for review
Use cases
- Resolving design conflicts when aesthetics and accessibility requirements diverge
- Validating that spacing, typography, and interaction patterns follow universal principles
- Making design decisions for edge cases not covered by your design system's tokens or components
- Ensuring WCAG compliance across contrast, color usage, focus states, and keyboard navigation
- Establishing consistent visual hierarchy and interaction feedback across multiple surfaces
- Design system maintainers and contributors
- Product designers making decisions outside their system's scope
- Frontend engineers validating design principle compliance during implementation
- Accessibility auditors and QA teams checking WCAG requirements
- Teams resolving design-system gaps or principle conflicts
typeui-fundamentals FAQ
No. Your design system wins for concrete values (colors, sizes, tokens, component specs). These principles provide the structural reasoning behind those decisions and fill gaps the system doesn't cover. If they conflict, the design system takes precedence — flag the conflict for review.
Accessibility is non-negotiable and overrides aesthetic preferences everywhere. If a principle (especially an accessibility rule) conflicts with your design preference, the principle wins. Resolve the conflict by adjusting the aesthetic approach.
No. These files focus only on universal design principles. For workflow phases, quality audits, anti-patterns, or industry-specific guidance, consult your vertical skill or team-specific documentation.
Use ui-principles.md for hierarchy and layout; spacing-principles.md for gaps and rhythm; ux-principles.md for interaction and states; typography-principles.md for type decisions; accessibility.md for WCAG compliance. Load them after your design system.
Yes. They apply to every surface and design system. They explain the universal 'why' behind patterns, not the specific 'what' tokens to use — that comes from your design system.
Full instructions (SKILL.md)
Source of truth, from bergside/typeui.
name: typeui-fundamentals description: Universal UI/UX design principles covering visual hierarchy, interaction laws, typography foundations, and WCAG accessibility requirements. Use when making design decisions not covered by a specific design system, validating principle compliance, or resolving conflicts between aesthetics and accessibility. Design-system-agnostic and applies to every surface. license: MIT metadata: author: typeui.sh
Design Fundamentals — Agent Instructions
Universal design principles that define why patterns work, how to apply them correctly, and what accessibility requirements are non-negotiable. These are timeless, design-system-agnostic foundations that apply to every surface regardless of vertical or workflow phase.
Load order
Read these files after loading the design system (SKILL.md / DESIGN.md + token modules). The design system tells you what token to use; these files explain why that decision is correct and how to avoid common principle violations.
Module index
| File | Purpose |
|---|---|
| ui-principles.md | Universal visual design principles — hierarchy, layout rhythm, typography placement, color theory, depth & layering, interaction design, responsive adaptation, component behavior |
| spacing-principles.md | Spacing-specific principles — 4-point grid, proximity grouping, inner vs outer gaps, vertical and horizontal rhythm, heading→paragraph spacing, section and component spacing tiers |
| ux-principles.md | Interaction & control principles — 30 UX laws, button/control state contracts (9 states), hover/active technique palettes, touch targets, cognitive load, feedback loops |
| typography-principles.md | Typography-specific principles — type system foundations, scale & modular ratios, readability & measure, accessibility, responsive type, brand tone expression through type |
| accessibility.md | WCAG 2.1/2.2 compliance — contrast ratios, color-as-information rules, focus visibility, keyboard navigation, motion safety, target sizes, text spacing, semantic structure, ARIA |
What these files are NOT
These files do not define:
- Workflow phases (think → build → check → ship) — see
skills/vertical/SKILL.md - Quality gates or audits — see
skills/vertical/inspect.md,review.md,preflight.md - Anti-pattern catalogs — see
skills/vertical/anti-patterns.md - Industry-specific content — see
skills/vertical/team-social-saas.md - Design tokens or component specs — see
skills/design-system/SKILL.md
Conflict resolution
When sources disagree:
- Design system wins for concrete values (colors, sizes, spacing tokens, component specs).
- Fundamentals (this layer) win for structural principles (hierarchy, accessibility, motion logic).
- Vertical wins for process decisions AND content architecture (section order, required sections, industry tone).
Accessibility is non-negotiable at every level — it overrides aesthetic preferences everywhere.
When the design system is silent, these principles decide
Any design decision not covered by the system's tokens or component rules falls back to the principles here. Never contradict the design system — if a principle and a design-system rule conflict, the design system wins. Flag the conflict for review.
Related skills
More from bergside/typeui and the wider catalog.
better-icons
Search and retrieve SVGs from 200+ icon libraries via Iconify CLI and MCP server.
better-auth-best-practices
Configure Better Auth server and client with database adapters, sessions, plugins, and OAuth.
better-auth-security-best-practices
Secure Better Auth deployments with rate limiting, CSRF protection, session hardening, and audit logging.
create-auth
Scaffold and implement authentication in TypeScript/JavaScript apps using Better Auth with framework detection and OAuth setup.
create-auth
Scaffold and implement authentication in TypeScript/JavaScript apps using Better Auth
email-and-password-best-practices
Configure email verification, password reset flows, and security policies for Better Auth email/password authentication.