Proof-of-concept exploring architectural approaches for building one design system on top of another. EHMDS demonstrates four distinct patterns for layering a design system on FKUI (Försäkringskassan Design System).
Repository: https://github.com/pattespatte/ehmds-on-fkui-test
EHMDS (EHM Design System) is a proof-of-concept design system built on top of FKUI. Its purpose is to explore, demonstrate, and compare architectural approaches for building one design system on another.
Primary Hypothesis: A layered architecture is the most effective pattern for building a design system on top of another design system.
Live Demo: https://pattespatte.github.io/ehmds-on-fkui-test/
EHMDS demonstrates four distinct patterns for building on FKUI:
| Pattern | Complexity | Flexibility | Maintenance | Best For |
|---|---|---|---|---|
| Token Override | ⭐ Very Low | ⭐ Low | ⭐ Very Low | Visual changes only |
| Wrapper/Facade | ⭐⭐ Low-Medium | ⭐⭐⭐ High | ⭐⭐ Medium | API simplification |
| Extension | ⭐⭐⭐ Medium-High | ⭐⭐ Medium | ⭐⭐ Medium | Adding features |
| Composition | ⭐⭐⭐⭐ High | ⭐⭐⭐⭐ Very High | ⭐⭐⭐ High | Domain components |
Minimal code, visual changes only
Uses FKUI components as-is, only overriding CSS custom properties.
- Component:
EhmBadge(wrapsFBadge) - Code: ~10 lines (mostly CSS)
- Use Case: When you only need to change colors, fonts, or spacing
- Maintenance: Very low - automatic FKUI updates
Simplified API, same component
Wraps FKUI components with a simplified, customized EHMDS API.
- Component:
EhmCard(wrapsFCard) - Code: ~50 lines
- Use Case: When you want a simpler or different API than FKUI
- Maintenance: Low - may need testing on FKUI updates
FKUI features + EHMDS enhancements
Extends FKUI components with additional features while preserving all original functionality.
- Component:
EhmTextField(extendsFTextField) - Code: ~100 lines
- Use Case: When you need FKUI's features plus additional functionality
- Maintenance: Medium - may need updates on FKUI changes
Multiple FKUI components, one domain component
Combines multiple FKUI components into a higher-level, domain-specific component.
- Component:
EhmSearchBox(composesFTextField+FCrudButton+FExpandable) - Code: ~150 lines
- Use Case: When you need to combine multiple FKUI components into a pattern
- Maintenance: High - likely needs updates on FKUI changes
- Vue 3 (Composition API +
<script setup>) - TypeScript (full type safety throughout)
- Vite (build tool + dev server)
- Vue Router (routing for demo and docs)
- FKUI packages:
@fkui/vue,@fkui/design,@fkui/logic,@fkui/date,@fkui/theme-default
# Clone the repository
git clone https://github.com/pattespatte/ehmds-on-fkui-test.git
cd ehmds-on-fkui-test
# Install dependencies
npm install# Start the demo app (includes component demos and documentation)
npm run demo
# Build for production
npm run buildThe demo app serves both:
- Interactive component demos at
/ - Documentation pages at
/docs/*
src/
├── components/
│ ├── wrapper/ # Wrapper/Facade pattern
│ │ └── EhmCard.vue # Wraps FCard with custom API
│ ├── extension/ # Extension pattern
│ │ └── EhmTextField.vue # Extends FTextField with features
│ ├── composition/ # Composition pattern
│ │ └── EhmSearchBox.vue # Composes FTextField + FCrudButton + FExpandable
│ └── token-override/ # Token Override pattern
│ └── EhmBadge.vue # FBadge with CSS token overrides
├── assets/
│ └── global.css # Global styles, FKUI imports, EHMDS CSS variables
├── themes/
│ ├── default.ts # Theme configuration with generateCSSVariables()
│ └── types.ts # TypeScript type definitions for themes
├── App.vue # Demo app showcasing all components
├── main.ts # App entry point
├── index.ts # Design system entry point (plugin exports)
├── types.ts # Main EHMDS type definitions
├── vite-env.d.ts # Vue module type declarations
├── router/
│ └── index.ts # Vue Router configuration
└── utils/
└── markdown.ts # Markdown utility functions
docs/
└── architecture/ # Architecture pattern documentation
├── overview.md # High-level overview
├── comparison.md # Pattern comparison
├── token-override.md # Token override pattern docs
├── wrapper.md # Wrapper pattern docs
├── extension.md # Extension pattern docs
└── composition.md # Composition pattern docs
npm install # Install dependencies
npm run demo # Start demo app (includes demos and docs)
npm run build # Build design system for production (includes type check)
npm run preview # Preview production build
npm run type-check # Run TypeScript type checking
npm run lint # Lint code (ESLint)
npm run lint:fix # Auto-fix linting issues
npm run update:fkui-deps # Update FKUI dependencies to latest| EHMDS Component | Pattern | FKUI Component(s) | Status |
|---|---|---|---|
EhmBadge |
Token Override | FBadge |
✅ Implemented |
EhmCard |
Wrapper | FCard |
✅ Implemented |
EhmTextField |
Extension | FTextField |
✅ Implemented |
EhmSearchBox |
Composition | FTextField + FCrudButton + FExpandable |
✅ Implemented |
Important: EHMDS components actually USE FKUI components at runtime. This is not just a CSS dependency - the FKUI Vue components are instantiated and rendered.
FKUI components are imported from @fkui/vue:
import { FCard, FTextField, FCrudButton, FExpandable, FBadge } from '@fkui/vue';Detailed architecture documentation is available in the /docs directory:
- Architecture Overview
- Pattern Comparison
- Token Override Pattern
- Wrapper Pattern
- Extension Pattern
- Composition Pattern
See Architecture Overview for detailed ADRs (Architecture Decision Records):
- Layered Architecture - EHMDS sits between app and FKUI
- Multiple Patterns - Demonstrate all four patterns, not just one
- Prefix Convention -
Ehmprefix distinguishes from FKUI components - Real FKUI Usage - Components actually instantiate FKUI, not just CSS
When adding new components to EHMDS:
- Choose the appropriate pattern based on your needs
- Follow the conventions for that pattern
- Use TypeScript for all new components with proper type definitions
- Run type checking before committing:
npm run type-check - Document your decision in an ADR (Architecture Decision Record)
- Add to this catalog with the pattern used
- Test against FKUI updates to ensure compatibility
MIT - see LICENSE for details.
Built with ❤️ as a proof-of-concept for layered design system architecture