Frontend / Component library
Design System
A collection of reusable components, design tokens, and frontend patterns built with Angular.
It documents the building blocks this portfolio is made of: the tokens behind its dark, terminal-inspired look, the components extracted from its templates, and the conventions that keep them consistent. Every component is explorable in Storybook with live controls, accessibility checks and interaction tests.
- Components
- 9
- Directives
- 3
- Color tokens
- 12
Principles
Six rules every component follows.
Each principle maps to a concrete decision in the code, not a slogan.
01
Consistency
Every color, typeface and radius comes from the tokens in styles.css. Components combine Tailwind utilities built on those tokens instead of hard-coded values.
02
Reusability
Components are extracted from patterns that already repeat across the site. The signal-colored pill button appeared in eight templates before it became appButton.
03
Accessibility
Native elements first: appButton decorates a real <button> or <a>. Labels are required, errors are announced, and all motion respects prefers-reduced-motion.
04
Composition
Content projection over configuration. Cards, buttons and empty states accept any content and named slots instead of growing an input for every case.
05
Maintainability
Standalone, OnPush components with typed signal inputs. A build check fails if the documented tokens drift from the stylesheet.
06
Developer Experience
Each component has Storybook docs with live controls, actions, accessibility checks and interaction tests, all running against the real source.
Design tokens
The values behind the interface.
Taken from the @theme block in styles.css and the Tailwind CSS 4 defaults this project relies on. A build check keeps this list in sync with the stylesheet.
Colors
Ink
--color-ink · #0a0d12
Page background
Ink 2
--color-ink-2 · #0e1218
Recessed bands, read-only fields
Surface
--color-surface · #12161d
Cards, inputs, navigation
Surface 2
--color-surface-2 · #161b24
Raised chips, selected states
Line
--color-line · #1e2530
Hairline borders
Line soft
--color-line-soft · #171d27
Low-emphasis dividers
Foreground
--color-fg · #e7ebf2
Primary text
Foreground dim
--color-fg-dim · #7c8797
Secondary text, labels
Foreground faint
--color-fg-faint · #798391
Tertiary text: captions, metadata, footers (meets AA 4.5:1 on every dark surface)
Signal
--color-signal · #43e8c9
Primary accent, focus rings, primary actions
Signal dim
--color-signal-dim · #21493f
Accent borders on dark surfaces
Watch
--color-watch · #f5a623
Secondary accent, warnings and validation errors
Typography
Aa
Display
--font-display · .font-display
Headings and large figures
Aa
Body
--font-body · .font-body
Running text and UI copy
Aa
Mono
--font-mono · .font-mono
Eyebrows, data, code and badges
آب
Vazirmatn
.article-persian
Persian text, self-hosted
Hero headline
3rem → 4.5rem
Signals to interfaces
font-display text-5xl sm:text-6xl lg:text-7xl leading-[1.05]
Section heading (h2)
1.875rem → 3rem
Signals to interfaces
font-display text-3xl md:text-4xl lg:text-5xl
Item heading (h3)
1.25rem → 1.5rem
Signals to interfaces
font-display text-xl md:text-2xl
Lead
1.125rem
Signals to interfaces
text-lg text-fg-dim
Body
1rem
Signals to interfaces
text-base
Small / UI
0.875rem
Signals to interfaces
text-sm
Eyebrow
0.75rem
Signals to interfaces
font-mono text-xs uppercase tracking-[0.25em] text-signal
Badge
11px
Signals to interfaces
font-mono text-[11px]
Spacing
Tailwind's 4px scale (--spacing: 0.25rem). The steps used most:
- 1
0.25rem · Icon gaps
- 2
0.5rem · Inline gaps, chip padding
- 3
0.75rem · Stacked controls
- 4
1rem · Default gap
- 6
1.5rem · Card padding, mobile gutter
- 8
2rem · Group spacing
- 10
2.5rem · Tablet gutter
- 16
4rem · Heading to content, desktop gutter
- 28
7rem · Vertical section rhythm
Layout
.section-shell
max-width: 1400px
Centres page content
.section-pad
1.5rem → 2.5rem → 4rem → 6rem
Responsive horizontal gutter (base, md, lg, xl)
Breakpoints
- sm:40rem (640px) · Large phones
- md:48rem (768px) · Tablets
- lg:64rem (1024px) · Desktop navigation appears
- xl:80rem (1280px) · Wide gutters
Border radius
rounded-lg
0.5rem
Small floating labels
rounded-xl
0.75rem
Inputs, compact tiles
rounded-2xl
1rem
Cards and panels
rounded-full
9999px
Buttons, badges, avatars
Shadows & elevation
--shadow-glow-signal
Signal glow for highlighted surfaces (defined in @theme)
shadow-lg
Floating code snippets in the hero
.glass
Translucent panels over motion; elevation comes from blur, not shadow
Motion
Every animation checks prefers-reduced-motion and falls back to a static, fully legible state. Animations are driven by GSAP, loaded lazily in the browser only.
| Pattern | Duration | Easing | Behaviour | Source |
|---|---|---|---|---|
| Reveal | 0.9s | power3.out | Fade in from 24px below at 88% viewport | appReveal |
| Hero entrance | 0.9s | power3.out | Words stagger by 45ms | HeroComponent |
| Magnetic | 0.5s | power3.out | Follows the pointer up to 18px | appMagnetic |
| Tilt | 0.4s | power3.out | Up to 8° of 3D rotation | appTilt |
| Count-up | 1.6s | power2.out | Starts at 60% visibility | StatCounterComponent |
| Color transitions | 150ms | cubic-bezier(0.4, 0, 0.2, 1) | Hover and focus states | transition-colors |
| Ticker | 32s | linear | Continuous marquee | TickerTapeComponent |
Components
What's in the library.
Only components that exist in the codebase. Each one links to its Storybook docs: API, live controls, variants and accessibility notes.
Actions
Button
component button[appButton], a[appButton]
Primary, secondary, outline and ghost actions, with loading, disabled and icon-only states.
Copy Command
component app-copy-command
Shell command with copy-to-clipboard, success feedback and a manual-copy fallback.
Forms
Input
component app-input
Labelled text field with hint and error text. Supports [(value)] and Angular Forms.
Feedback
Badge
component app-badge
Monospace label for tags, technologies and statuses.
Data Display
Card
component app-card
Bordered surface, glass or dashed container with a projected footer slot.
Empty State
component app-empty-state
Explains why there is nothing to show and offers the next step.
Stat Counter
component app-stat-counter
Figure that counts up once it scrolls into view.
Ticker Tape
component app-ticker-tape
Decorative market-style marquee of short labels.
Layout
Section Heading
component app-section-heading
Eyebrow, h2 and description that open every portfolio section.
Architecture
How the components are built.
The conventions every component in the library follows, with the code they produce.
Component composition
Enhance native elements with attribute selectors instead of wrapping them, so semantics, focus and router links keep working.
<a appButton variant="outline" routerLink="/articles">
Read articles
</a>Inputs and outputs
Use signal input() with booleanAttribute for flags, so plain attributes work. Use model() for two-way state that can also be bound with [( )].
readonly loading = input(false, { transform: booleanAttribute });
readonly value = model('');Angular Signals
Derive host classes and ARIA state with computed(). OnPush components then update without lifecycle hooks or manual change detection.
protected readonly classes = computed(() =>
[BASE, VARIANTS[this.variant()], SIZES[this.size()]].join(' '));Content projection
Project content and use named slots for optional regions. Wrap a slot in an element with empty:hidden so it disappears when unused.
<app-card>
<h3>Title</h3>
<a cardFooter href="/books">View</a>
</app-card>Accessibility conventions
Visible labels, aria-describedby for hints and errors, aria-busy while loading, aria-label on icon-only buttons and configurable heading levels.
<button appButton iconOnly aria-label="Back to top">
<lucide-icon [img]="ArrowUp" />
</button>Styling conventions
Tailwind utilities built on design tokens. Variant maps hold complete class names so Tailwind can find them; prefer logical spacing (ms-, pe-) for RTL.
const VARIANTS: Record<ButtonVariant, string> = {
primary: 'bg-signal text-ink hover:bg-fg', …
};Naming conventions
Elements use the app- prefix, attribute selectors and directives use app (appButton, appReveal). Stories sit next to the component as name.stories.ts.
shared/components/button/
button.component.ts
button.stories.tsComponent API design
Small typed unions instead of boolean flags, safe defaults (buttons default to type="button") and one obvious way to do each thing.
variant: 'primary' | 'secondary' | 'outline' | 'ghost'
size: 'sm' | 'md' | 'lg'Explore every component in Storybook
Change inputs with controls, watch outputs in the actions panel, run accessibility checks and preview each component in RTL and at every breakpoint.