@mdkk11/mdkk-ui

@mdkk11/mdkk-ui is a React component library built on top of react-aria-components. It provides a strict component architecture, accessible behavior primitives, and a Brutalist-oriented design token system.

Core Principles

• Public API is a stable contract.
• Accessibility and interaction behavior are delegated to react-aria-components.
• Styling and visual language are controlled by design tokens and semantic CSS variables.
• Components follow a strict 3-tier architecture: Public -> Adapter -> Primitive.

Installation

npm install @mdkk11/mdkk-ui react react-dom
# or
pnpm add @mdkk11/mdkk-ui react react-dom

No additional Tailwind plugin is required for component state styling.

Quick Start

1) Import base styles

import '@mdkk11/mdkk-ui/dist/index.css';

@mdkk11/mdkk-ui no longer styles body automatically. Wrap your app root with mdkk-theme to opt into design-system base typography/colors:

export function AppRoot() {
  return <div className='mdkk-theme'>{/* app */}</div>;
}

If you want global behavior, add class="mdkk-theme" to your app body.

2) Configure Tailwind v4

// tailwind.config.js
import { mdkkPlugin } from '@mdkk11/mdkk-ui/tailwind-plugin';

export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@mdkk11/mdkk-ui/dist/**/*.{js,ts,jsx,tsx}',
  ],
  plugins: [mdkkPlugin],
};

/* src/index.css */
@import "tailwindcss";
@config "../tailwind.config.js";

3) Use components

import { Button, Card, CardHeader, CardTitle, CardContent } from '@mdkk11/mdkk-ui';

export function Example() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hello</CardTitle>
      </CardHeader>
      <CardContent>
        <Button variant='primary'>Click</Button>
      </CardContent>
    </Card>
  );
}

Subpath imports are also supported for tighter bundles:

import { Button } from '@mdkk11/mdkk-ui/button';
import { TextField } from '@mdkk11/mdkk-ui/text-field';

React Aria Dependency

This library intentionally depends on react-aria-components for core behavior. react-aria-components is managed internally by @mdkk11/mdkk-ui as a runtime dependency. Consumers do not need to install it separately unless they also import it directly.

react and react-dom remain peer dependencies and should be provided by the consumer app.

• Primitive layer may import react-aria-components.
• Public layer should not leak raw react-aria-components prop types.

See docs/DEPENDENCY_POLICY.md for details.

Icons

Icon is publicly exported and fully standardized on Lucide.

• Source and rules: docs/ICONS.md
• Third-party license notice: THIRD_PARTY_LICENSES.md

Documentation Map

• docs/ARCHITECTURE.md: component architecture, layers, and responsibilities
• docs/DESIGN_SYSTEM.md: tokens, semantic variables, Brutalist styling strategy
• docs/PUBLIC_API_STANDARDS.md: API naming and prop design standards
• docs/COMPONENT_CATALOG.md: exported components and usage notes
• docs/ICONS.md: icon source policy

Exported Surface

The package exports:

• components from src/index.ts
• component subpaths (for example @mdkk11/mdkk-ui/button, @mdkk11/mdkk-ui/text-field)
• Tailwind plugin via @mdkk11/mdkk-ui/tailwind-plugin
• built CSS via @mdkk11/mdkk-ui/dist/index.css

Development

npm run storybook
npm run typecheck
npm run check

Bundle Size Check

Track package artifact sizes in dev with size-limit:

pnpm -s size:check

Current public-entry targets:

• dist/index.js (raw): 4 KB
• dist/tailwind-plugin.js (gzip): 1 KB
• dist/index.css (gzip): 11 KB

If a budget exceeds, investigate regressions first. Raise budgets only when increase is intentional and justified in the PR. Representative component targets can be added later if needed.

Git Hooks

This repository uses lefthook for local quality gates.

pnpm run hooks:install

• pre-commit: pnpm -s check
• pre-push: pnpm -s typecheck and pnpm -s test:unit

CI

GitHub Actions CI is defined in .github/workflows/ci.yml. It runs static checks, type checks, unit tests, Storybook interaction tests, and build validation on PRs/pushes to main.

Storybook VRT (Chromatic)

Visual regression testing workflow is defined in .github/workflows/vrt.yml.

• runs on PRs/pushes to main and via workflow_dispatch
• uses chromaui/action@v1 (major pinned) with onlyChanged: true
• defines externals globs for CSS/assets/design-system token changes
• runs in strict mode (exitZeroOnChanges: false) to fail on visual changes

Configure this repository secret before running VRT:

• CHROMATIC_PROJECT_TOKEN

Keep Chromatic Visual Tests as a required check in branch protection.

License

MIT