@dimm-city/components

A cyberpunk UI component library for Dimm City projects, built with Svelte 5 and TypeScript.

🎨 Features

• 21 Production-Ready Components: From buttons to timelines, all themed for cyberpunk aesthetics
• Svelte 5 Native: Built with modern runes ($props, $state, $derived, $effect)
• TypeScript First: Fully typed with strict mode enforcement
• Cyberpunk Aesthetic: Dark, neon-accented design system with glow effects
• Accessible: WCAG 2.1 AA compliant with 231 comprehensive tests
• Performant: Tree-shakeable, optimized animations, reduced motion support
• Design Tokens: Customizable CSS custom properties with --dc- prefix
• Well Tested: 231 tests across 14 test files, cross-browser validated
• Fully Documented: Complete docs, examples, and migration guide

🚀 Installation

npm install @dimm-city/components

📖 Usage

Import Styles

Add the global styles to your app's layout or main entry point:

<script>
	import '@dimm-city/components/styles';
</script>

Use Components

<script>
	import { Button, Card, Heading } from '@dimm-city/components';
</script>

<Card variant="bordered">
	<Heading level={2}>Welcome to Dimm City</Heading>
	<p>The city don't love you.</p>
	<Button variant="primary" text="Get Started" href="/campaign" />
</Card>

🎨 Design System

The library includes a comprehensive design system with:

Color Palette

• Brand Yellow: #FFD700 - Primary brand color
• Cyber Magenta: #D946EF - Secondary accent
• Neon Cyan: #00FFFF - Tertiary accent
• Toxic Green: #00FF00 - Success/tech accent
• Danger Red: #FF4500 - Warning/danger

Typography

• Display Font: lixdu (primary), Orbitron (fallback) - headings, logos
• Body Font: Titillium Web, Tomorrow, Inter (fallback) - content, UI
• Monospace: Courier New (code blocks)

The custom lixdu display font is bundled with the component library and loaded automatically when you import the styles - no manual setup required!

Design Tokens

All design tokens are available as CSS custom properties with the --dc- prefix:

/* Colors */
--dc-color-brand-yellow: #ffd700;
--dc-color-cyber-magenta: #d946ef;
--dc-color-neon-cyan: #00ffff;

/* Spacing */
--dc-space-xs: 0.25rem;
--dc-space-sm: 0.5rem;
--dc-space-md: 1rem;
--dc-space-lg: 1.5rem;

/* Effects */
--dc-glow-yellow: 0 0 20px rgba(255, 215, 0, 0.6);
--dc-glow-magenta: 0 0 20px rgba(217, 70, 239, 0.6);

See src/lib/styles/tokens.css for the complete list.

🧰 Utilities

The library includes utility functions for common tasks:

Animation Utilities

import {
  animateCounter,
  throttle,
  prefersReducedMotion,
} from "@dimm-city/components";

// Animate a number counter
animateCounter(element, 0, 100, 2000);

// Throttle scroll events
const handleScroll = throttle(() => {
  console.log("Scrolling...");
}, 200);

// Check motion preferences
if (!prefersReducedMotion()) {
  // Add animations
}

Observer Utilities

import { observeViewport, isInViewport } from "@dimm-city/components";

// Observe when element enters viewport
const observer = observeViewport(
  (entry) => {
    console.log("Element visible!");
  },
  { threshold: 0.5, once: true },
);

observer.observe(myElement);

Accessibility Utilities

import { trapFocus, announce, generateId } from "@dimm-city/components";

// Trap focus in modal
const cleanup = trapFocus(modalElement);

// Announce to screen readers
announce("Form submitted successfully", "polite");

// Generate unique IDs
const id = generateId("button"); // "dc-1-1234567890"

📦 Components (21 Total)

Foundation (4)

• Button - CTA buttons with primary, secondary, ghost, danger variants
• Card - Content containers with bordered, elevated, glass variants
• Heading - Semantic h1-h6 with visual variants and glitch effects
• Text - Typography component with sizes, colors, weights

Effects (4)

• GlitchText - RGB channel shift animation with configurable intensity
• Skeleton - Loading placeholders (text, circular, rectangular) with shimmer
• ParallaxBackground - Scroll-based parallax effect with configurable speed
• TiltCard - 3D tilt effect on mouse movement with optional glare

Layout (2)

• Section - Page section wrapper with hero, feature, dark variants
• Grid - Responsive grid layout with auto-fit or fixed columns

Navigation (3)

• Navigation - Sticky header with mobile menu and keyboard navigation
• Footer - Flexible section-based footer with links and copyright
• Breadcrumb - Hierarchical navigation with ARIA support

Content (5)

• Avatar - User avatar with image or initials fallback, 4 sizes, 4 colors
• AvatarGroup - Overlapping avatars with overflow indicator (+N)
• Badge - Status indicators (default, success, warning, danger, new)
• ProgressBar - Animated progress with ARIA attributes and glow effects
• Timeline - Vertical/horizontal event timeline with status indicators

Feedback (2)

• Countdown - Time-based countdown with multiple display modes (days, hours, precise)
• ActivityTicker - Auto-scrolling activity feed with pause on hover

Utilities

• Animation utilities: animateCounter, throttle, debounce, prefersReducedMotion
• Observer utilities: observeViewport, observeResize, isInViewport
• Accessibility utilities: trapFocus, announce, generateId, getContrastRatio

📚 View Complete Component Documentation →

🎯 Development

Prerequisites

• Node.js >= 22.0.0
• npm or pnpm

Setup

# Install dependencies
npm install

# Start dev server
npm run dev

# Build package
npm run build

# Type check
npm run check

# Lint & format
npm run lint
npm run format

Testing

# Run all tests
npm test

# Run tests in UI mode
npm run test:ui

# Run accessibility tests only
npm run test:a11y

# Debug tests
npm run test:debug

The library includes 231 comprehensive tests covering:

• Component functionality and interactions
• Accessibility (WCAG 2.1 AA compliance)
• Cross-browser compatibility
• Responsive design
• Keyboard navigation
• Screen reader support

Package

# Create distributable package
npm run package

This will generate the dist/ folder with compiled components ready for publishing.

📦 Publishing (Maintainers Only)

The package is automatically published to npm when a version tag is pushed to the repository.

Publishing Process

Easy way - Use the automated release script:

# Interactive mode (prompts for version)
../packages/release.sh

# Specify version bump type
../packages/release.sh patch    # 0.1.1 -> 0.1.2
../packages/release.sh minor    # 0.1.1 -> 0.2.0
../packages/release.sh major    # 0.1.1 -> 1.0.0

# Specify exact version
../packages/release.sh 0.1.2
../packages/release.sh v0.1.2   # 'v' prefix is optional

# Skip confirmation prompts (for automation)
../packages/release.sh 0.1.2 -y
../packages/release.sh patch --yes

# Show help
../packages/release.sh --help

The script will:

• Check you're on main branch with no uncommitted changes
• Pull latest changes
• Update version in package.json
• Create commit and tag
• Push to origin (with confirmation prompts unless -y flag is used)

Manual way - If you prefer to do it manually:

1. Update version in package.json

   cd dimm-city-components
   npm version patch --no-git-tag-version  # or minor/major

2. Commit, tag, and push

   VERSION=$(node -p "require('./package.json').version")
   cd ..
   git add dimm-city-components/package.json
   git commit -m "Release @dimm-city/components@${VERSION}"
   git tag "v${VERSION}"
   git push --follow-tags

GitHub Actions Workflow - After pushing the tag, the workflow will automatically:

• Run linter and type checks
• Run all tests
• Build the package
• Verify package contents
• Publish to npm with provenance
• Create a GitHub release

Manual Publishing (if needed)

If you need to publish manually:

# Ensure you're on main branch with latest changes
git checkout main
git pull

# Build the package
npm run package

# Publish to npm (requires npm login or trusted publishing configured)
npm publish --access public

Prerequisites

• NPM Trusted Publishing: Configure trusted publishing on npmjs.com (one-time setup)
  1. Go to npmjs.com and navigate to your package settings
  2. Add a new trusted publisher with these details:
     • Provider: GitHub Actions
     • Organization/User: dimm-city
     • Repository: dimm-city-web
     • Workflow: publish-components.yml
     • Environment: (leave blank or specify if using environments)
  3. Save the configuration
• Permissions: Must be a member of the @dimm-city npm organization

Note: Trusted publishing uses OpenID Connect (OIDC) for authentication, eliminating the need for long-lived NPM tokens. The workflow automatically authenticates using temporary, workflow-specific credentials.

🔄 Migration Guide

Migrating an existing Dimm City project to use this library? We've got you covered!

📖 Read the Complete Migration Guide →

The migration guide includes:

• Component mapping (old → new)
• Step-by-step migration process
• Before/after code examples
• Breaking changes documentation
• Testing strategies
• Troubleshooting tips

Quick Start Migration

<!-- After: Library component -->
<script>
	import { Button } from '@dimm-city/components';
</script>

<!-- Before: Custom component -->
<AugmentedButton href="/start">Get Started</AugmentedButton>
<Button variant="primary" href="/start" text="Get Started" augmented={true} />

📚 Documentation

• Getting Started - Installation and setup
• Design System - Colors, typography, tokens
• Components - Complete API reference
• Examples - Live interactive examples
• Migration Guide - Migrate existing projects
• Changelog - Version history

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Follow the existing code style (Prettier + ESLint)
2. Use Svelte 5 runes syntax
3. Ensure TypeScript strict mode compliance
4. Add accessibility features (ARIA, keyboard support)
5. Write tests for new components or features
6. Test across browsers and devices
7. Document all props and usage
8. Update CHANGELOG.md with your changes

📄 License

MIT

🔗 Links

• Dimm City RPG
• GitHub Repository
• Component Examples
• Full Documentation

The city don't love you. 🌃