Forem: hanui-io

Building Accessible React Components - What We Learned from WCAG Compliance

hanui-io — Fri, 26 Dec 2025 05:16:13 +0000

Ever failed an accessibility audit?

I have. Multiple times.

Missing aria attributes, no keyboard navigation, invisible focus indicators... when you're rushing to meet deadlines, these get overlooked. Then the audit fails and your timeline implodes.

So when we built HANUI (a React component library), we baked accessibility in from day one.

What's WCAG/KWCAG?

WCAG (Web Content Accessibility Guidelines) is the international standard. KWCAG is the Korean version, largely based on WCAG 2.1/2.2.

The core principles:

Principle	What It Means
Perceivable	Alt text, color contrast
Operable	Keyboard access, focus indicators
Understandable	Labels, error messages
Robust	Valid markup, proper ARIA usage

How We Handle Button Accessibility

// HANUI Button with loading state
<Button loading>Saving...</Button>

Renders as:

<button aria-busy="true" aria-disabled="true" disabled>
  <svg class="animate-spin" aria-hidden="true">...</svg>
  Saving...
</button>

What's automatic:

aria-busy: Tells screen readers something is loading
aria-disabled: Communicates disabled state
aria-hidden on spinner: Decorative elements shouldn't be read

Icon Button Warnings

// This triggers a dev mode warning
<Button size="icon" iconLeft={<Search />} />
// ⚠️ Console: Icon-only buttons must have an aria-label

// Correct usage
<Button size="icon" iconLeft={<Search />} aria-label="Search" />

Buttons without text are meaningless to screen readers. We warn developers before it becomes an audit failure.

Form Accessibility

<FormField status="error" required>
  <FormLabel>Email</FormLabel>
  <Input type="email" placeholder="example@email.com" />
  <FormError>Invalid email format</FormError>
</FormField>

Renders as:

<div>
  <label for=":r1:">
    Email
    <span aria-hidden="true">*</span>
    <span class="sr-only">(required)</span>
  </label>
  <input
    id=":r1:"
    type="email"
    aria-invalid="true"
    aria-required="true"
    aria-describedby=":r1:-error"
  />
  <div id=":r1:-error" role="alert" aria-live="polite">
    Invalid email format
  </div>
</div>

What's automatic:

id/htmlFor connection via React.useId()
aria-describedby links input to error message
aria-invalid signals error state
role="alert" makes screen readers announce errors immediately
Required indicator: visual * + screen reader text "(required)"

Modal Accessibility

<Modal open={isOpen} onClose={() => setIsOpen(false)}>
  <ModalHeader>
    <ModalTitle>Confirm Delete</ModalTitle>
  </ModalHeader>
  <ModalBody>Are you sure you want to delete this?</ModalBody>
  <ModalFooter>
    <Button variant="tertiary" onClick={() => setIsOpen(false)}>
      Cancel
    </Button>
    <Button variant="danger">Delete</Button>
  </ModalFooter>
</Modal>

What HANUI Modal handles automatically:

1. Focus Trap

When modal opens, Tab cycles only within the modal. Can't escape to page behind.

2. Focus Return

When modal closes, focus returns to the element that opened it.

3. Escape Key

Pressing Escape closes the modal.

4. ARIA Attributes

<div role="dialog" aria-modal="true" aria-labelledby="modal-title">
  <h2 id="modal-title">Confirm Delete</h2>
  ...
</div>

Building this manually is complex. We use Radix UI primitives which handle it correctly.

Select/Dropdown Accessibility

<Select>
  <SelectTrigger>
    <SelectValue placeholder="Select..." />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="seoul">Seoul</SelectItem>
    <SelectItem value="busan">Busan</SelectItem>
  </SelectContent>
</Select>

Keyboard behavior:

Enter/Space: Open dropdown
↑/↓: Navigate options
Enter: Select
Escape: Close
Typing: Jump to matching option

ARIA attributes:

aria-haspopup="listbox"
aria-expanded
role="listbox", role="option"
aria-selected

Focus Indicators

/* HANUI default focus style */
focus:outline-none
focus:ring-2
focus:ring-primary
focus:ring-offset-2

Never just outline: none. Always provide alternative focus styling. Keyboard users need to see where they are.

Color Contrast

Design system colors should meet WCAG contrast requirements:

Normal text: 4.5:1 minimum
Large text: 3:1 minimum
UI components: 3:1 minimum

KRDS color tokens are designed to meet these requirements. Use them and you're covered.

Common Accessibility Checklist

HANUI handles most of these, but always verify:

[ ] All images have alt text
[ ] Icon buttons have aria-label
[ ] Lighthouse accessibility score 90+
[ ] All functionality works with keyboard only

Why Build It In?

We could have shipped components faster without accessibility. But:

Retrofitting is painful - Adding accessibility after the fact means touching every component
Developers forget - When rushing, aria attributes get skipped
Audits are expensive - Failed audits mean rework and delayed launches
It's the right thing to do - The web should be usable by everyone

Try It

npx hanui add button form-field modal select

aria attributes, keyboard navigation, focus management - all included.

Pass your accessibility audit on the first try.

GitHub: https://github.com/hanui-o/hanui
Documentation: https://hanui.io

Implementing Dark Mode with CSS Variables

hanui-io — Tue, 23 Dec 2025 05:39:13 +0000

How do you implement dark mode?

/* Like this? */
.dark .card {
  background: #1a1a1a;
  color: #ffffff;
}

.light .card {
  background: #ffffff;
  color: #1a1a1a;
}

Adding .dark branches to every component doubles your CSS.

CSS variables make it much cleaner.

Basic Structure

:root {
  --color-bg: #ffffff;
  --color-text: #1a1a1a;
  --color-border: #e5e5e5;
}

.dark {
  --color-bg: #1a1a1a;
  --color-text: #ffffff;
  --color-border: #333333;
}

.card {
  background: var(--color-bg);
  color: var(--color-text);
  border: 1px solid var(--color-border);
}

One .card style. Mode switch just changes variable values.

Semantic Tokens

Name colors by purpose for better clarity:

:root {
  /* Light mode */
  --color-surface: #ffffff; /* cards, modals */
  --color-background: #f5f5f5; /* page background */
  --color-text-primary: #1a1a1a; /* main text */
  --color-text-secondary: #666666; /* secondary text */
  --color-border: #e5e5e5;
}

.dark {
  --color-surface: #262626;
  --color-background: #1a1a1a;
  --color-text-primary: #ffffff;
  --color-text-secondary: #a3a3a3;
  --color-border: #404040;
}

--color-surface is clearer than --color-gray-100. No need to look up what it means.

Using with Tailwind

// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        surface: 'var(--color-surface)',
        background: 'var(--color-background)',
        'text-primary': 'var(--color-text-primary)',
        'text-secondary': 'var(--color-text-secondary)',
        border: 'var(--color-border)',
      },
    },
  },
};

<div className="bg-surface text-text-primary border-border">
  <p className="text-text-secondary">Secondary text</p>
</div>

No dark: prefix needed. It switches automatically.

Mode Toggle Logic

// theme-toggle.tsx
function ThemeToggle() {
  const [isDark, setIsDark] = useState(false);

  useEffect(() => {
    // Detect system preference
    const prefersDark = window.matchMedia(
      '(prefers-color-scheme: dark)'
    ).matches;
    // Check saved preference
    const saved = localStorage.getItem('theme');

    if (saved === 'dark' || (!saved && prefersDark)) {
      document.documentElement.classList.add('dark');
      setIsDark(true);
    }
  }, []);

  function toggle() {
    const newValue = !isDark;
    setIsDark(newValue);

    if (newValue) {
      document.documentElement.classList.add('dark');
      localStorage.setItem('theme', 'dark');
    } else {
      document.documentElement.classList.remove('dark');
      localStorage.setItem('theme', 'light');
    }
  }

  return (
    <button onClick={toggle}>{isDark ? 'Light Mode' : 'Dark Mode'}</button>
  );
}

Key is adding/removing dark from document.documentElement.classList.

Preventing Flash

SSR or Next.js has a flash problem on page load. Solution:

<!-- layout.tsx or _document.tsx -->
<head>
  <script dangerouslySetInnerHTML={{
    __html: `
      (function() {
        var theme = localStorage.getItem('theme');
        var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
        if (theme === 'dark' || (!theme && prefersDark)) {
          document.documentElement.classList.add('dark');
        }
      })();
    `
  }} />
</head>

This script runs before render, no flash.

Color Palette Tips

Don't just invert for dark mode:

❌ Light: #ffffff → Dark: #000000
   Too much contrast, hurts eyes

✅ Light: #ffffff → Dark: #1a1a1a
   Slightly lighter black is comfortable

Same for text:

❌ Light: #000000 → Dark: #ffffff
   Pure white causes eye strain

✅ Light: #1a1a1a → Dark: #f5f5f5
   Slightly darker white is better

Proven Color Set

Battle-tested combinations:

:root {
  /* Surface */
  --color-surface: #ffffff;
  --color-surface-elevated: #ffffff;

  /* Background */
  --color-background: #f5f5f5;

  /* Text */
  --color-text-primary: #171717;
  --color-text-secondary: #525252;
  --color-text-tertiary: #a3a3a3;

  /* Border */
  --color-border: #e5e5e5;
  --color-border-strong: #d4d4d4;

  /* Primary */
  --color-primary: #3b82f6;
  --color-primary-hover: #2563eb;
}

.dark {
  --color-surface: #262626;
  --color-surface-elevated: #333333;

  --color-background: #171717;

  --color-text-primary: #fafafa;
  --color-text-secondary: #a3a3a3;
  --color-text-tertiary: #737373;

  --color-border: #404040;
  --color-border-strong: #525252;

  --color-primary: #60a5fa;
  --color-primary-hover: #3b82f6;
}

Primary colors should be brighter in dark mode for visibility.

Watch Out For

1. Images

/* Invert logo in dark mode */
.dark .logo {
  filter: invert(1);
}

/* Or prepare two versions */

2. Shadows

:root {
  --shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

.dark {
  /* Darker shadows in dark mode */
  --shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
}

3. No Hardcoded Colors

/* ❌ Dark mode won't work */
<div className="bg-white text-black">

/* ✅ Use variables */
<div className="bg-surface text-text-primary">

Summary

Define colors as CSS variables
Change only variable values in .dark
Components reference only variables
Use semantic names (surface, text-primary, etc.)
Add flash prevention script for SSR

This makes dark mode maintenance much easier.

CSS, darkmode, CSSvariables, TailwindCSS, React, frontend

How Long Does It Take to Build a Design System Button? Before/After Comparison

hanui-io — Mon, 22 Dec 2025 02:20:52 +0000

"Where's the design system documentation?"

If you've worked on government or enterprise projects, you've heard this. Then you open a 200-page PDF, hunt for color codes, copy spacing values, debate whether the border-radius is 4px or 8px... half a day gone for one button.

Today I'm showing you actual code. Before and after using a component library.

Case 1: Building a Button

Before: Implementing from Design System PDF

// Step 1: Find color values in design guide (10 min)
// Primary: #0A5ECA, Hover: #0852B2, Active: #064794...

// Step 2: Write CSS (30 min)
.btn-primary {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 8px;
  min-width: 80px;
  height: 48px;
  padding: 0 20px;
  border-radius: 6px;
  font-size: 16px;
  font-weight: 500;
  background-color: #0A5ECA;
  color: #FFFFFF;
  border: none;
  cursor: pointer;
  transition: background-color 0.2s;
}

.btn-primary:hover {
  background-color: #0852B2;
}

.btn-primary:active {
  background-color: #064794;
}

.btn-primary:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

.btn-primary:focus-visible {
  outline: 2px solid #0A5ECA;
  outline-offset: 2px;
}

// Step 3: Write component (20 min)
function Button({ children, ...props }) {
  return (
    <button className="btn-primary" {...props}>
      {children}
    </button>
  );
}

// Step 4: Add variants? (1 hour)
// secondary, tertiary, danger... find each color, add CSS

// Step 5: Add sizes? (30 min)
// xs, sm, md, lg, xl... calculate height, padding, font-size

// Total time: 2-3 hours
// And next project? Start over.

After: Using HANUI

npx hanui add button

import { Button } from '@/components/ui/button';

// Done. Use immediately.
<Button>Default Button</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="danger" size="lg">Delete</Button>
<Button loading>Saving...</Button>
<Button iconLeft={<Search />}>Search</Button>

Time: 10 seconds

8 variants, 6 sizes, loading state, icon support - all included. Accessibility? aria-busy, aria-disabled, focus ring - all applied.

Case 2: Form Field

Before: Manual Implementation

function FormField({ label, error, helperText, required, children }) {
  const id = useId();
  const errorId = `${id}-error`;
  const helperId = `${id}-helper`;

  return (
    <div className="form-field">
      <label htmlFor={id} className="form-label">
        {label}
        {required && <span className="required-mark">*</span>}
      </label>

      {/* How do I pass id, aria-describedby to children? */}
      {/* cloneElement? Context? */}
      {children}

      {error && (
        <div id={errorId} className="form-error" role="alert">
          {error}
        </div>
      )}

      {helperText && (
        <div id={helperId} className="form-helper">
          {helperText}
        </div>
      )}
    </div>
  );
}

// aria-describedby connection?
// Input error styling?
// Error icon?
// Screen reader support?
// ... complexity grows

After: Using HANUI

npx hanui add form-field input

import { FormField, FormLabel, FormError, FormHelperText } from '@/components/ui/form-field';
import { Input } from '@/components/ui/input';

<FormField status="error" required>
  <FormLabel>Email</FormLabel>
  <Input type="email" placeholder="example@email.com" />
  <FormError>Invalid email format</FormError>
</FormField>

<FormField status="success">
  <FormLabel>Username</FormLabel>
  <Input value="hanui" />
  <FormHelperText>Username is available</FormHelperText>
</FormField>

Context automatically connects id and aria attributes. Error/success icons auto-display. role="alert", aria-live="polite" applied.

Case 3: Header + Mega Menu

This one takes days to build from scratch.

Before: Consider All These

Responsive (mobile hamburger menu)
Mega menu dropdown
Keyboard navigation (Tab, Arrow, Escape)
Focus trap
Scroll behavior (sticky/hide)
WAI-ARIA patterns

Honestly, building this properly takes a week.

After: Using HANUI

npx hanui add header

import { HeaderWithMegaMenu } from '@/components/ui/header';

<HeaderWithMegaMenu
  title="Government24"
  navigation={[
    { label: 'Services', items: [...] },
    { label: 'Guide', items: [...] },
  ]}
  stickyBehavior="auto"
/>

Mega menu, mobile support, keyboard navigation, scroll behavior - all included.

Real Comparison

Task	Manual	With Library
Button (with variants)	2-3 hours	10 seconds
Form Field (accessible)	3-4 hours	10 seconds
Header + Mega Menu	3-5 days	10 seconds
Select (search, multi)	1-2 days	10 seconds
Modal (focus trap)	Half day	10 seconds

Things often missed when building manually:

aria-describedby connection
aria-expanded, aria-haspopup
Focus management
Escape key to close
Screen reader announcements

The Hidden Cost

The real problem with manual implementation isn't just time.

1. Inconsistency

/* Developer A */
.btn {
  border-radius: 4px;
}

/* Developer B */
.button {
  border-radius: 6px;
}

/* Developer C */
.custom-btn {
  border-radius: 8px;
}

2. Missing Accessibility

When you're busy, aria attributes get skipped. "I'll add them later" becomes "failed the audit."

3. Maintenance Hell

Design system updates? Manually update all components across all projects.

Summary

Building design system components from scratch: hours to days.
Using a well-built component library: seconds.

If you're working on Korean government projects, HANUI provides KRDS-compliant React components out of the box.

npx hanui init
npx hanui add button input select form-field header modal

5 minutes to set up. Spend the rest of your time on business logic.

GitHub: https://github.com/hanui-o/hanui
Documentation: https://hanui.io

Tailwind CSS v4 Migration Guide

hanui-io — Fri, 19 Dec 2025 02:31:00 +0000

Tailwind v4 is out. Have you migrated yet?

A lot has changed from v3 to v4. Config files, syntax, and the build system.

What Changed

1. CSS-first Configuration

The biggest change. No more tailwind.config.js required.

// v3: tailwind.config.js required
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
    },
  },
};

/* v4: configure directly in CSS */
@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
}

One CSS file does it all.

2. @tailwind → @import

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

Down to a single line.

3. Native CSS Variables

v4 generates all values as CSS variables:

/* Variables auto-generated by v4 */
:root {
  --color-blue-500: #3b82f6;
  --spacing-4: 1rem;
  --font-size-lg: 1.125rem;
}

/* Use directly in your CSS */
.custom-box {
  background: var(--color-blue-500);
  padding: var(--spacing-4);
}

Use variables directly without Tailwind classes.

Migration Steps

Step 1: Upgrade Package

npm install tailwindcss@latest

Step 2: Update CSS File

/* old globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* ↓ change to */
@import "tailwindcss";

Step 3: Migrate Config (Optional)

Move existing config to CSS or keep as is:

/* Moving to CSS */
@import "tailwindcss";

@theme {
  /* Custom colors */
  --color-brand: #3b82f6;
  --color-brand-dark: #2563eb;

  /* Custom fonts */
  --font-family-sans: 'Inter', sans-serif;

  /* Custom spacing */
  --spacing-18: 4.5rem;
}

// Keeping JS config (v4 supports this too)
// tailwind.config.js
export default {
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
    },
  },
};

Both work. Migrate gradually to CSS if you prefer.

Syntax Changes

1. Opacity Syntax

<!-- v3 -->
<div class="bg-blue-500/50">

<!-- v4 (same) -->
<div class="bg-blue-500/50">

No change here.

2. Arbitrary Values

<!-- v3 -->
<div class="w-[200px] bg-[#ff0000]">

<!-- v4 (same) -->
<div class="w-[200px] bg-[#ff0000]">

Same as before.

3. Container Queries

Built-in support in v4:

<!-- v3: needed @tailwindcss/container-queries plugin -->
<!-- v4: works out of the box -->
<div class="@container">
  <div class="@lg:grid-cols-2">
    Changes based on container size
  </div>
</div>

4. 3D Transforms

<!-- New in v4 -->
<div class="rotate-x-45 rotate-y-30 perspective-500">
  3D transforms
</div>

Common Errors

1. PostCSS Config

// postcss.config.js - for v4
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

Use @tailwindcss/postcss instead of tailwindcss.

2. @apply Warnings

/* v4 may warn about @apply */
.btn {
  @apply px-4 py-2 bg-blue-500;
}

v4 discourages @apply. CSS variables are preferred:

/* Recommended approach */
.btn {
  padding: var(--spacing-2) var(--spacing-4);
  background: var(--color-blue-500);
}

3. Plugin Compatibility

Some v3 plugins may not work with v4. Check compatibility:

# Official plugins mostly supported
npm install @tailwindcss/forms@latest
npm install @tailwindcss/typography@latest

When to Migrate

Good to Go Now

New projects
Projects with minimal custom config
Want to leverage CSS variables

Wait a Bit

Heavy legacy plugin usage
Extensive @apply usage
Production stability is priority

v4 Benefits

Build Speed: Oxide engine is much faster
Simpler Config: CSS-first reduces config files
Native CSS Variables: Easier design token usage
Bundle Size: More optimized output

Summary

v4 Migration Checklist:

[ ] Install tailwindcss@latest
[ ] Change @tailwind → @import "tailwindcss"
[ ] Update postcss.config.js
[ ] Move custom config to @theme (optional)
[ ] Check plugin compatibility
[ ] Review @apply warnings

No rush. v3 will be maintained for a while. Use v4 for new projects, migrate existing ones gradually.

Building a Design System with Tailwind CSS

hanui-io — Thu, 18 Dec 2025 05:49:21 +0000

"Tailwind is utility classes. Does it work for design systems?"

Yes. Actually, it works great.

The core of a design system is consistency. Colors, spacing, typography following defined rules.

Tailwind enforces that. p-4 is always 16px. text-sm is always 14px. No developer variance.

Basic Structure

Design Tokens (CSS Variables)
    ↓
Tailwind Config (tailwind.config)
    ↓
Utility Classes (bg-primary, text-sm)
    ↓
Components

1. Color Tokens

// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          100: '#dbeafe',
          500: '#3b82f6', // base
          600: '#2563eb', // hover
          700: '#1d4ed8', // active
        },
        gray: {
          50: '#f9fafb',
          100: '#f3f4f6',
          500: '#6b7280',
          900: '#111827',
        },
      },
    },
  },
};

Now you can use bg-primary-500, text-gray-900.

CSS Variables Are Better

/* globals.css */
:root {
  --color-primary-500: #3b82f6;
  --color-primary-600: #2563eb;
}

.dark {
  --color-primary-500: #60a5fa;
  --color-primary-600: #3b82f6;
}

// tailwind.config.ts
colors: {
  primary: {
    500: 'var(--color-primary-500)',
    600: 'var(--color-primary-600)',
  },
}

Dark mode switching happens automatically.

2. Typography

// tailwind.config.ts
fontSize: {
  'display-lg': ['48px', { lineHeight: '1.2', fontWeight: '700' }],
  'display-md': ['36px', { lineHeight: '1.2', fontWeight: '700' }],
  'heading-lg': ['24px', { lineHeight: '1.4', fontWeight: '600' }],
  'heading-md': ['20px', { lineHeight: '1.4', fontWeight: '600' }],
  'body-lg': ['18px', { lineHeight: '1.6' }],
  'body-md': ['16px', { lineHeight: '1.6' }],
  'body-sm': ['14px', { lineHeight: '1.6' }],
},

<h1 className="text-display-lg">Large Title</h1>
<h2 className="text-heading-lg">Medium Title</h2>
<p className="text-body-md">Body text</p>

Responsive Typography

CSS variables make responsive easy:

:root {
  --fs-display-lg: 36px;
}

@media (min-width: 1024px) {
  :root {
    --fs-display-lg: 48px;
  }
}

fontSize: {
  'display-lg': ['var(--fs-display-lg)', { lineHeight: '1.2' }],
}

Single text-display-lg handles mobile and desktop.

3. Spacing

Tailwind's default spacing works, but for custom:

spacing: {
  'xs': '4px',
  'sm': '8px',
  'md': '16px',
  'lg': '24px',
  'xl': '32px',
  '2xl': '48px',
  '3xl': '64px',
},

<div className="p-md mb-lg">{/* padding: 16px, margin-bottom: 24px */}</div>

Honestly, Tailwind defaults (p-4, mb-6) are sufficient. It's an 8px grid system.

4. Building Components

With tokens set up, build components:

// Button.tsx
const variants = {
  primary: 'bg-primary-500 text-white hover:bg-primary-600',
  secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
  outline: 'border border-primary-500 text-primary-500 hover:bg-primary-50',
};

const sizes = {
  sm: 'h-8 px-3 text-body-sm',
  md: 'h-10 px-4 text-body-md',
  lg: 'h-12 px-6 text-body-lg',
};

export function Button({ variant = 'primary', size = 'md', ...props }) {
  return (
    <button
      className={`${variants[variant]} ${sizes[size]} rounded-md font-medium`}
      {...props}
    />
  );
}

Type-Safe with cva

import { cva, type VariantProps } from 'class-variance-authority';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium',
  {
    variants: {
      variant: {
        primary: 'bg-primary-500 text-white hover:bg-primary-600',
        secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
      },
      size: {
        sm: 'h-8 px-3 text-body-sm',
        md: 'h-10 px-4 text-body-md',
        lg: 'h-12 px-6 text-body-lg',
      },
    },
    defaultVariants: {
      variant: 'primary',
      size: 'md',
    },
  }
);

type ButtonProps = VariantProps<typeof buttonVariants>;
// { variant?: 'primary' | 'secondary', size?: 'sm' | 'md' | 'lg' }

Autocomplete and type checking included.

5. Distribute as Preset

For team use or multiple projects, create a preset:

// my-preset.ts
const myPreset = {
  theme: {
    extend: {
      colors: { /* ... */ },
      fontSize: { /* ... */ },
    },
  },
};

export default myPreset;

// tailwind.config.ts
import myPreset from './my-preset';

export default {
  presets: [myPreset],
  // project-specific additions
};

Design System Checklist

Must-haves:

[ ] Color tokens (primary, secondary, gray, danger, success)
[ ] Typography scale (display, heading, body, label)
[ ] Spacing system (8px grid recommended)
[ ] Border radius
[ ] Shadows
[ ] Base components (Button, Input, Card, etc.)

For Government Projects

Need to follow KRDS (Korean Design System).

Color codes, font sizes, spacing - all specified. Setting it up manually takes a day.

HANUI has KRDS tokens pre-applied as a Tailwind preset.

// tailwind.config.ts
import hanuiPreset from '@hanui/react/tailwind.preset';

export default {
  presets: [hanuiPreset],
};

<p className="text-krds-body-md text-krds-gray-90">KRDS styled text</p>
<Button className="bg-krds-primary-50">KRDS button</Button>

Colors, typography, responsive - all KRDS compliant.

TailwindCSS, designsystem, React, CSSvariables, cva, frontend

Building a shadcn/ui Style Component Library for Korean Government Design System

hanui-io — Fri, 12 Dec 2025 04:03:23 +0000

shadcn/ui changed how we think about component libraries. Instead of installing a package, you copy the source code into your project. You own it. You customize it.

I built HANUI using the same approach - but for KRDS (Korean Government Design System).

Here's how it works under the hood.

The Architecture

┌─────────────────────────────────────────────┐
│  CLI (npx hanui add button)                 │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│  Component Registry (components.json)       │
│  - Component definitions                    │
│  - Dependencies                             │
│  - File paths                               │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│  Your Project                               │
│  components/ui/button.tsx  ← copied here    │
└─────────────────────────────────────────────┘

The CLI

The CLI is the entry point. It handles:

init - Sets up your project
add - Copies components to your project
diff - Shows what changed (coming soon)

npx hanui init
# Creates:
# - components.json (config)
# - Copies variables.css (design tokens)
# - Updates tailwind.config.ts (adds preset)

npx hanui add button modal input
# Copies:
# - components/ui/button.tsx
# - components/ui/modal.tsx
# - components/ui/input.tsx
# - Any dependencies (like cn utility)

Component Structure

Each component follows a consistent pattern:

// button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';

const buttonVariants = cva(
  // Base styles
  'inline-flex items-center justify-center rounded font-medium transition-colors',
  {
    variants: {
      variant: {
        primary: 'bg-krds-primary-base text-white hover:bg-krds-primary-60',
        secondary: 'bg-krds-gray-10 text-krds-gray-90 hover:bg-krds-gray-20',
        tertiary:
          'bg-transparent text-krds-primary-base hover:bg-krds-primary-5',
        danger: 'bg-krds-danger-base text-white hover:bg-krds-danger-60',
      },
      size: {
        sm: 'h-8 px-3 text-krds-label-sm',
        md: 'h-10 px-4 text-krds-label-md',
        lg: 'h-12 px-6 text-krds-label-lg',
      },
    },
    defaultVariants: {
      variant: 'primary',
      size: 'md',
    },
  }
);

interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  loading?: boolean;
}

export function Button({
  className,
  variant,
  size,
  loading,
  children,
  ...props
}: ButtonProps) {
  return (
    <button
      className={cn(buttonVariants({ variant, size }), className)}
      disabled={loading || props.disabled}
      aria-busy={loading}
      {...props}
    >
      {loading && <Spinner className="mr-2" aria-hidden />}
      {children}
    </button>
  );
}

Key patterns:

cva for type-safe variants
cn utility for merging classNames
KRDS tokens in Tailwind classes (krds-primary-base, krds-label-md)
Accessibility built-in (aria-busy)

Design Token System

KRDS has specific color, typography, and spacing values. We implement them as CSS variables + Tailwind preset.

CSS Variables (variables.css)

:root {
  /* Colors */
  --krds-color-light-primary-50: #256ef4;
  --krds-color-light-primary-60: #0b50d0;

  /* Semantic tokens */
  --krds-primary-base: var(--krds-color-light-primary-50);
  --krds-primary-text: var(--krds-color-light-primary-60);

  /* Typography */
  --krds-fs-body-md: 17px;
  --krds-fs-heading-lg: 24px;
}

.dark {
  /* Dark mode overrides */
  --krds-primary-base: var(--krds-color-light-primary-50);
  --krds-primary-text: var(--krds-color-light-primary-40);
}

Tailwind Preset (tailwind.preset.ts)

const hanuiPreset = {
  theme: {
    extend: {
      colors: {
        'krds-primary': {
          DEFAULT: 'var(--krds-primary-base)',
          base: 'var(--krds-primary-base)',
          text: 'var(--krds-primary-text)',
          50: 'var(--krds-color-light-primary-50)',
          60: 'var(--krds-color-light-primary-60)',
        },
      },
      fontSize: {
        'krds-body-md': ['17px', { lineHeight: '150%' }],
        'krds-heading-lg': [
          'var(--krds-fs-heading-lg)',
          { lineHeight: '150%', fontWeight: '700' },
        ],
      },
    },
  },
};

This gives you Tailwind classes that map to KRDS values:

<p className="text-krds-body-md text-krds-gray-90">KRDS-compliant text</p>

Radix UI Integration

Complex components (Modal, Select, Tabs) are built on Radix UI primitives.

Why Radix?

Accessibility - WAI-ARIA compliant out of the box
Unstyled - We apply KRDS styling
Composable - Flexible compound component API

// modal.tsx
import * as Dialog from '@radix-ui/react-dialog';

export function Modal({ children, ...props }) {
  return (
    <Dialog.Root {...props}>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/50" />
        <Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white rounded-lg p-6">
          {children}
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

export const ModalTitle = Dialog.Title;
export const ModalDescription = Dialog.Description;
export const ModalClose = Dialog.Close;

We get:

Focus trap
Escape key handling
Screen reader announcements
Scroll lock

For free. We just add KRDS styling.

Why This Approach?

1. Full Control

You own the code. Need to change how buttons look? Edit button.tsx. No fighting with library internals.

2. No Runtime Dependency

Components are copied, not imported from node_modules. Your bundle only includes what you use.

3. Tailwind Native

Everything uses Tailwind. Consistent with modern React projects.

4. Type Safety

TypeScript + cva = autocomplete for variants, compile-time checks.

5. Accessible by Default

Radix primitives + ARIA attributes. KWCAG compliance built-in.

Trade-offs

No automatic updates - You have to manually update components
Larger initial setup - More files in your project
Learning curve - Understanding the component structure

For KRDS projects where customization is inevitable, these trade-offs are worth it.

Get Started

npx hanui init
npx hanui add button input modal select tabs

GitHub: https://github.com/hanui-o/hanui
Documentation: https://hanui.io

Tags: #react #typescript #tailwindcss #designsystem #opensource

React Accessibility Checklist - Pass Government Audits First Time

hanui-io — Thu, 11 Dec 2025 01:27:49 +0000

Ever failed an accessibility audit?

"Non-compliant with WCAG" - seeing that label is painful. Fix it, resubmit, fix again... deadlines slip.

Here are the accessibility issues that commonly fail in React projects. Check these before the audit.

Top 5 Common Failures

1. Image Alt Text

// ❌ Wrong
<img src="/logo.png" />

// ✅ Correct
<img src="/logo.png" alt="Company logo" />

// ✅ Decorative images get empty alt
<img src="/decoration.png" alt="" />

Screen readers can't see images, so alt text describes them.

2. Form Label Connection

// ❌ Label not connected to input
<label>Email</label>
<input type="email" />

// ✅ Connected with htmlFor
<label htmlFor="email">Email</label>
<input id="email" type="email" />

// ✅ Or wrap with label
<label>
  Email
  <input type="email" />
</label>

Clicking the label should focus the input.

3. Button Text

// ❌ Icon-only button without label
<button>
  <SearchIcon />
</button>

// ✅ Add aria-label
<button aria-label="Search">
  <SearchIcon />
</button>

// ✅ Or add visually hidden text
<button>
  <SearchIcon />
  <span className="sr-only">Search</span>
</button>

Without text, screen readers just say "button". Tell users what it does.

4. Keyboard Accessibility

// ❌ div as button - not keyboard accessible
<div onClick={handleClick}>Click me</div>

// ✅ Use actual button
<button onClick={handleClick}>Click me</button>

// ✅ If you must use div
<div
  role="button"
  tabIndex={0}
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
  Click me
</div>

Must be reachable with Tab and activatable with Enter/Space.

5. Focus Indicator

/* ❌ Don't remove focus outline without replacement */
button {
  outline: none;
}

/* ✅ If removing, provide alternative */
button:focus-visible {
  outline: none;
  box-shadow: 0 0 0 2px #0A5ECA;
}

Keyboard users need to see where they are.

Component Checklists

Modal/Dialog

<div role="dialog" aria-modal="true" aria-labelledby="modal-title">
  <h2 id="modal-title">Modal Title</h2>
  {/* content */}
</div>

[ ] role="dialog" or <dialog> element
[ ] aria-modal="true"
[ ] Title connected with aria-labelledby
[ ] Focus moves inside on open
[ ] Focus returns to trigger on close
[ ] Escape key closes it
[ ] Focus trap (can't tab outside)

Dropdown/Select

<button
  aria-haspopup="listbox"
  aria-expanded={isOpen}
  aria-controls="dropdown-list"
>
  Select...
</button>
<ul id="dropdown-list" role="listbox">
  <li role="option" aria-selected={selected}>Option 1</li>
</ul>

[ ] aria-haspopup="listbox" or "menu"
[ ] aria-expanded state management
[ ] Arrow keys navigate options
[ ] Enter to select
[ ] Escape to close

Tabs

<div role="tablist">
  <button role="tab" aria-selected={activeTab === 0} aria-controls="panel-0">
    Tab 1
  </button>
</div>
<div role="tabpanel" id="panel-0" aria-labelledby="tab-0">
  Panel content
</div>

[ ] role="tablist", role="tab", role="tabpanel"
[ ] aria-selected state
[ ] Arrow keys switch tabs
[ ] Tab and panel connected (aria-controls, aria-labelledby)

Automated Testing Tools

eslint-plugin-jsx-a11y

npm install -D eslint-plugin-jsx-a11y

// .eslintrc.js
module.exports = {
  extends: ['plugin:jsx-a11y/recommended'],
};

Catches accessibility issues while coding.

axe DevTools

Chrome extension. Scan any page for accessibility issues.

Lighthouse

Chrome DevTools > Lighthouse > Accessibility. Score of 100 means basics are covered.

The Easy Way

Honestly, tracking all this while developing is hard.

That's why using a component library with built-in accessibility helps.

HANUI is a KRDS-based React component library with all the above accessibility features built in.

npx hanui add button modal select

Button aria-label warnings, modal focus traps, select keyboard navigation... all included.

Pre-Audit Checklist

[ ] All images have alt text
[ ] All form elements have connected labels
[ ] All functionality works with keyboard only
[ ] Focus indicators are visible
[ ] Color contrast is 4.5:1 or higher
[ ] Modal/dropdown keyboard behavior works
[ ] No eslint-plugin-jsx-a11y errors
[ ] Lighthouse accessibility score 90+

Check all these before the audit and pass first time.

React, accessibility, WCAG, a11y, aria, screenreader, frontend

HANUI - Copy-Paste React Components for Korean Government Design System

hanui-io — Wed, 10 Dec 2025 01:16:25 +0000

Building a Korean government website? You need to follow KRDS (Korean Government Design System).

The problem: KRDS provides a 200+ page PDF guide. Colors, spacing, typography, components - all specified in detail. But no code. You have to implement everything yourself.

That's where HANUI comes in.

What is HANUI?

HANUI is a React component library that implements KRDS. Copy-paste style, like shadcn/ui.

npx hanui init
npx hanui add button

That's it. Button component with KRDS styling is now in your project.

Why "Copy-Paste"?

Traditional component libraries (MUI, Chakra) give you pre-built components. You install them, import them, use them.

The problem? Customization is painful. You fight against the library's opinions.

HANUI copies the actual source code into your project. You own it. Change anything you want.

your-project/
├── components/
│   └── ui/
│       ├── button.tsx      ← Your code now
│       ├── input.tsx
│       └── modal.tsx

What's Included

Components (20+)

Button, Input, Textarea, Select
Modal, Drawer, Toast
Tabs, Accordion
Table, Pagination
Form validation with react-hook-form + zod
And more...

Design Tokens

KRDS color palette (primary, secondary, gray, danger, warning, success, info)
Typography scale (display, heading, body, label)
Spacing system (8px grid)
Responsive breakpoints

Accessibility

KWCAG 2.2 compliant (Korean Web Content Accessibility Guidelines)
Keyboard navigation
Screen reader support
Focus management

Tech Stack

React 18+
TypeScript
Tailwind CSS - Utility-first styling
Radix UI - Headless accessible primitives
class-variance-authority - Type-safe variants

Quick Start

# Initialize in your project
npx hanui init

# Add components you need
npx hanui add button input modal

# Use them

import { Button } from '@/components/ui/button';

function App() {
  return (
    <Button variant="primary" size="md">
      Submit
    </Button>
  );
}

Who is This For?

Korean government/public sector projects - Need KRDS compliance
SI developers - Tight deadlines, need ready-to-use components
Korean startups - Want Korean-style design without building from scratch

What HANUI is NOT

Not a full design system documentation
Not a replacement for understanding KRDS guidelines
Not production-ready for all edge cases (yet - it's beta)

We're honest: this is an early-stage open source project. But it's already saving hours of work for developers who need KRDS-compliant React components.

Get Started

npx hanui init

GitHub: https://github.com/hanui-o/hanui
Documentation: https://hanui.io

Tags: #react #opensource #designsystem #tailwindcss #webdev