hua-ux Framework Usage

hua-ux Framework Usage Skill

This skill guides you on how to develop Next.js applications using the hua-ux framework.

🚨 Required Guidelines for Claude Assistants

Required Checks Before Using Framework

IF (creating a new page or component) THEN
  1. Use hua-ux framework components first
     → Wrap page with `HuaUxPage`
     → Use components from `@hua-labs/ui` first
  2. Generate translation files together
     → `translations/ko/{namespace}.json`
     → `translations/en/{namespace}.json`
  3. Prefer Server Components
     → Add `'use client'` only when client features are needed
END IF

Core Philosophy

"You don't need to know Next.js. Just configure and tell AI what to do."

Framework Structure

Top Layer: Framework & Config

• hua-ux.config.ts: Framework configuration
• HuaUxLayout: Automatic Provider setup
• HuaUxPage: Page wrapper (Motion, i18n, SEO automatically applied)

Bottom Layer: Core Packages

• @hua-labs/ui: UI component library
• @hua-labs/motion-core: Motion/animations
• @hua-labs/i18n-core: Internationalization
• @hua-labs/state: State management

Key Patterns

1. Page Creation Pattern

// app/my-page/page.tsx
import { HuaUxPage } from '@hua-labs/hua-ux/framework';
import { useTranslation } from '@hua-labs/i18n-core';

export default function MyPage() {
  const { t } = useTranslation('my-page');
  
  return (
    <HuaUxPage title={t('title')} description={t('description')}>
      <h1>{t('title')}</h1>
      {/* content */}
    </HuaUxPage>
  );
}

Important:

• Wrapping with HuaUxPage automatically applies Motion, i18n, SEO
• Add translation keys to translations/{language}/my-page.json
• Create as Server Component (default)

2. Client Component Creation Pattern

// components/MyComponent.tsx
'use client';

import { Card, Button } from '@hua-labs/ui';
import { useMotion } from '@hua-labs/hua-ux/framework';
import { useTranslation } from '@hua-labs/i18n-core';

export function MyComponent() {
  const { t } = useTranslation('my-component');
  const motion = useMotion();
  
  return (
    <Card ref={motion.ref} style={motion.style}>
      <h2>{t('title')}</h2>
      <Button>{t('button')}</Button>
    </Card>
  );
}

Important:

• Client components require 'use client'
• Utilize framework components (@hua-labs/ui, @hua-labs/motion-core)

3. Translation File Pattern

// translations/ko/my-page.json
{
  "title": "Title",
  "description": "Description",
  "button": "Button"
}

// translations/en/my-page.json
{
  "title": "Title",
  "description": "Description",
  "button": "Button"
}

Important:

• Add all translation keys to both Korean and English
• Namespace should match page name

Available Components

@hua-labs/ui

• Button, Card, Input, Modal, Alert, Toast, Table, Form, etc.
• See ai-context.md for detailed list

@hua-labs/hua-ux/framework

• HuaUxPage: Page wrapper
• HuaUxLayout: Layout
• UnifiedProviders: Provider unification
• useMotion: Unified motion hook
• useData: Client data fetching
• fetchData: Server data fetching

Configuration File

hua-ux.config.ts

import { defineConfig } from '@hua-labs/hua-ux/framework';

export default defineConfig({
  preset: 'product',  // 'product' or 'marketing'
  
  i18n: {
    defaultLanguage: 'ko',
    supportedLanguages: ['ko', 'en'],
  },
  
  motion: {
    defaultPreset: 'product',
    enableAnimations: true,
  },
});

Preset Selection:

• 'product': For product pages (professional, efficient)
• 'marketing': For marketing pages (dramatic, eye-catching)

Guidelines for Claude Code Generation

1. When Creating Pages:

   • Wrap with HuaUxPage
   • Generate translation files together
   • Use useTranslation hook
   • Prefer Server Components

2. When Creating Components:

   • Add 'use client' directive (for client components)
   • Utilize framework components
   • Consider applying motion

3. When Adding Translations:

   • Add both Korean and English
   • Maintain namespace consistency

4. When Changing Configuration:

   • Only modify hua-ux.config.ts
   • Prefer Preset (over manual configuration)

References

• ai-context.md: Detailed project structure explanation
• .cursorrules: Cursor IDE rules
• Framework docs: node_modules/@hua-labs/hua-ux/README.md