Design Judgment in Code: Beyond AI-Generated UI — Practical Techniques for Embedding Intent into Types, Tokens, and Conditionals

type ButtonVariant =
  | 'primary'     // Most visually dominant action
  | 'secondary'   // Supporting action
  | 'destructive' // Dangerous actions (delete, cancel)
  | 'ghost'       // Understated actions
  | 'link';       // Text-link appearance
 
type ButtonSize =
  | 'sm'  // 34px – compact layouts
  | 'md'  // 44px – touch target standard (accessible)
  | 'lg'; // 54px – primary CTA emphasis
 
type ButtonState =
  | 'default'
  | 'loading'   // In-progress action (cursor-wait, disabled)
  | 'disabled'  // Cannot interact
  | 'success'   // Action completed
  | 'error';    // Action failed
 
interface ButtonProps {
  variant?: ButtonVariant;
  size?: ButtonSize;
  state?: ButtonState;
  children: React.ReactNode;
  onClick?: () => void | Promise<void>;
  ariaLabel?: string;
}
 
export function Button({
  variant = 'primary',
  size = 'md',
  state = 'default',
  children,
  onClick,
  ariaLabel,
}: ButtonProps) {
  // This object embeds design judgment for every combination
  const variantStyles = {
    primary: {
      default: 'bg-primary text-white hover:bg-primary-dark focus:ring-2 focus:ring-primary/30',
      loading: 'bg-primary/70 text-white',
      disabled: 'bg-primary/40 text-white/70 cursor-not-allowed',
      success: 'bg-success text-white',
      error: 'bg-error text-white',
    },
    secondary: {
      default: 'bg-surface-alt text-text-primary hover:bg-gray-300 focus:ring-2 focus:ring-primary/20',
      loading: 'bg-surface-alt/70 text-text-primary',
      disabled: 'bg-surface-alt/50 text-text-primary/50 cursor-not-allowed',
      success: 'bg-success/20 text-success-dark border border-success/50',
      error: 'bg-error/20 text-error-dark border border-error/50',
    },
    destructive: {
      default: 'bg-error text-white hover:bg-error-dark focus:ring-2 focus:ring-error/30',
      loading: 'bg-error/70 text-white',
      disabled: 'bg-error/40 text-white/70 cursor-not-allowed',
      success: 'bg-success text-white',
      error: 'bg-error-dark text-white',
    },
    ghost: {
      default: 'text-text-primary hover:bg-surface-alt focus:ring-2 focus:ring-gray-300',
      loading: 'text-text-primary/70 bg-surface-alt/50 cursor-wait',
      disabled: 'text-text-primary/40 cursor-not-allowed',
      success: 'text-success-dark bg-success/10',
      error: 'text-error-dark bg-error/10',
    },
    link: {
      default: 'text-primary underline hover:no-underline focus:ring-2 focus:ring-primary/30',
      loading: 'text-primary/70 cursor-wait',
      disabled: 'text-primary/40 cursor-not-allowed',
      success: 'text-success underline',
      error: 'text-error underline',
    },
  };
 
  const sizeStyles = {
    sm: 'px-2 py-1.5 text-sm',
    md: 'px-4 py-2 text-base min-h-[44px]', // 44px: WCAG accessibility
    lg: 'px-6 py-3 text-lg min-h-[54px]',   // 54px: emphasis
  };
 
  const isDisabled = state === 'disabled' || state === 'loading';
 
  return (
    <button
      className={`font-semibold rounded-md transition-all duration-150 focus:outline-none ${
        sizeStyles[size]
      } ${variantStyles[variant][state]}`}
      disabled={isDisabled}
      onClick={state === 'loading' ? undefined : onClick}
      aria-busy={state === 'loading'}
      aria-disabled={isDisabled}
      aria-label={ariaLabel}
    >
      {state === 'loading' ? (
        <span className="flex items-center gap-2">
          <span className="animate-spin w-4 h-4 border-2 border-current border-t-transparent rounded-full" />
          Processing…
        </span>
      ) : (
        children
      )}
    </button>
  );
}

type ElementType = React.ElementType;
 
interface PolymorphicProps<T extends ElementType = 'button'> {
  as?: T; // The element to render
  variant?: ButtonVariant;
  size?: ButtonSize;
  children: React.ReactNode;
}
 
type PolymorphicRef<T extends ElementType> = React.ComponentPropsWithRef<T>['ref'];
 
export const Button = React.forwardRef(
  <T extends ElementType = 'button'>(
    { as: Component = 'button' as T, variant = 'primary', size = 'md', ...props }: PolymorphicProps<T>,
    ref: PolymorphicRef<T>
  ) => {
    return (
      <Component
        ref={ref}
        className={`button button--${variant} button--${size}`}
        {...props}
      />
    );
  }
);
 
// Usage
<Button>Submit</Button>                    // <button>
<Button as="a" href="/login">Sign in</Button> // <a>
<Button as="label" htmlFor="agree">I agree</Button> // <label>

type ValidationState = 'default' | 'validating' | 'invalid' | 'valid';
 
interface InputProps {
  value: string;
  onChange: (val: string) => void;
  validationState?: ValidationState;
  errorMessage?: string;
  successMessage?: string;
  isRequired?: boolean;
}
 
export function Input({
  value,
  onChange,
  validationState = 'default',
  errorMessage,
  successMessage,
  isRequired,
}: InputProps) {
  const inputId = `input-${Math.random().toString(36).slice(2)}`;
 
  // Judgment: different states require different visual + accessibility treatment
  const getStateStyles = (state: ValidationState): string => {
    switch (state) {
      case 'validating':
        // Feedback: "we're checking this"
        return 'border-blue-400 bg-blue-50 cursor-wait';
 
      case 'invalid':
        // Alert: "this won't work"
        return 'border-red-500 bg-red-50 focus:ring-red-300';
 
      case 'valid':
        // Confirmation: "good to go"
        return 'border-green-500 bg-green-50 focus:ring-green-300';
 
      default:
        // Neutral: awaiting input
        return 'border-gray-300 focus:ring-blue-300';
    }
  };
 
  // Judgment: accessibility attributes must match state
  const getAriaProps = () => {
    const attrs: Record<string, any> = {
      'aria-invalid': validationState === 'invalid',
      'aria-busy': validationState === 'validating',
      'aria-required': isRequired,
    };
 
    // When state changes to invalid/validating, link error/status message
    if (validationState === 'invalid' || validationState === 'validating') {
      attrs['aria-describedby'] = `${inputId}-status`;
    }
 
    return attrs;
  };
 
  return (
    <div className="flex flex-col gap-2">
      <input
        id={inputId}
        type="text"
        value={value}
        onChange={(e) => onChange(e.target.value)}
        className={`border-2 px-3 py-2 rounded-md transition-all ${getStateStyles(
          validationState
        )}`}
        {...getAriaProps()}
      />
 
      {/* Judgment: error/success messages have different ARIA roles */}
      {validationState === 'invalid' && errorMessage && (
        <div
          id={`${inputId}-status`}
          role="alert"
          aria-live="assertive"
          className="text-red-600 text-sm font-medium"
        >
          {errorMessage}
        </div>
      )}
 
      {validationState === 'valid' && successMessage && (
        <div
          id={`${inputId}-status`}
          role="status"
          aria-live="polite"
          className="text-green-600 text-sm font-medium"
        >
          {successMessage}
        </div>
      )}
 
      {validationState === 'validating' && (
        <div className="text-blue-600 text-sm flex items-center gap-1">
          <span className="animate-spin w-3 h-3 border-2 border-current border-t-transparent rounded-full" />
          Validating…
        </div>
      )}
    </div>
  );
}

export function Card({ children }: { children: React.ReactNode }) {
  return <div className="border rounded-lg p-6">{children}</div>;
}
 
export function CardHeader({ children }: { children: React.ReactNode }) {
  return <div className="border-b pb-4 mb-4 font-semibold text-lg">{children}</div>;
}
 
export function CardBody({ children }: { children: React.ReactNode }) {
  return <div>{children}</div>;
}
 
export function CardFooter({ children }: { children: React.ReactNode }) {
  return (
    <div className="border-t mt-4 pt-4 flex gap-3 justify-end">{children}</div>
  );
}
 
// Usage
<Card>
  <CardHeader>User Profile</CardHeader>
  <CardBody>
    <p>Name: Alice</p>
    <p>Email: alice@example.com</p>
  </CardBody>
  <CardFooter>
    <Button>Cancel</Button>
    <Button variant="primary">Save</Button>
  </CardFooter>
</Card>

interface CardProps {
  header?: React.ReactNode;
  body: React.ReactNode;
  footer?: React.ReactNode;
}
 
export function Card({ header, body, footer }: CardProps) {
  return (
    <div className="border rounded-lg p-6">
      {header && <div className="border-b pb-4 mb-4 font-semibold text-lg">{header}</div>}
      <div>{body}</div>
      {footer && <div className="border-t mt-4 pt-4 flex gap-3 justify-end">{footer}</div>}
    </div>
  );
}
 
// Usage
<Card
  header="User Profile"
  body={<p>Name: Alice</p>}
  footer={<Button>Save</Button>}
/>

interface ListProps<T> {
  data: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
  renderEmpty?: () => React.ReactNode;
  isLoading?: boolean;
}
 
export function List<T>({
  data,
  renderItem,
  renderEmpty,
  isLoading,
}: ListProps<T>) {
  if (isLoading) return <div className="p-4 text-center">Loading…</div>;
  if (data.length === 0)
    return renderEmpty?.() ?? <div className="p-4 text-center">No items</div>;
 
  return <div className="space-y-4">{data.map((item, i) => renderItem(item, i))}</div>;
}
 
// Usage
<List
  data={users}
  renderItem={(user) => (
    <div className="border p-4">
      <p>{user.name}</p>
      <p className="text-gray-500">{user.email}</p>
    </div>
  )}
  renderEmpty={() => <p className="text-gray-400">No users found</p>}
/>

# Design Token Contract
 
Your component implementations must respect these tokens ONLY.
 
## Colors (oklch)
- primary: oklch(0.55 0.2 260)
- secondary: oklch(0.65 0.15 260)
- error: oklch(0.55 0.2 25)
- success: oklch(0.58 0.15 142)
 
## Spacing (Fibonacci)
- xs: 0.25rem (4px)
- sm: 0.5rem (8px)
- md: 1rem (16px)
- lg: 1.5rem (24px)
- xl: 2.5rem (40px)
- xxl: 4rem (64px)
 
## Constraints
- Button min-height: 44px (touch accessibility)
- Modal backdrop: opacity 40%, color surface-dim
- Focus rings: 2px, primary color, offset 2px
- Transitions: 200ms duration, cubic-bezier(0.4, 0, 0.2, 1)

# Button Component Implementation
 
Reference the design token contract above.
 
## Requirements
 
1. **Variants** (type-enforce these 5):
   - primary: most visually dominant (uses primary token)
   - secondary: supporting role
   - destructive: danger signal (red-based, grabs attention)
   - ghost: minimal emphasis
   - link: text-only
 
2. **Sizes** (type-enforce these 3):
   - sm: 34px
   - md: 44px (WCAG 2.5.5 touch accessibility minimum)
   - lg: 54px
 
3. **States**:
   - loading: cursor-wait + opacity-70 + disabled
   - disabled: opacity-50 + cursor-not-allowed
   - Include aria-busy and aria-disabled attributes
 
4. **Reasoning in Comments**:
   - Explain why min-h-44px exists (accessibility, not aesthetics)
   - Note why loading state includes cursor-wait (UX feedback)
   - Document why aria-* attributes are conditional
 
Format: React function component, TypeScript with strict types, Tailwind for styling.

# AI Output Review
 
Evaluate generated Button component:
 
□ **Token Compliance**
  ✓ All colors from oklch token list?
  ✓ No hardcoded hex/rgb values?
  ✓ Spacing from Fibonacci list?
 
□ **Type Safety**
  ✓ variant, size, state are string literals (not string)?
  ✓ Invalid combinations rejected at compile time?
 
□ **Accessibility**
  ✓ aria-* attributes conditional on state?
  ✓ aria-busy when loading?
  ✓ aria-disabled when disabled?
 
□ **Documentation**
  ✓ Comments explain "why" for each condition?
  ✓ No obvious gaps in reasoning?
 
□ **Code Quality**
  ✓ Avoid deeply nested ternaries?
  ✓ Extract complex logic into named variables?

// Button.stories.tsx
export default {
  title: 'Components/Button',
  component: Button,
};
 
export const Primary = {
  args: { variant: 'primary', children: 'Submit' },
};
 
export const PrimaryLoading = {
  args: { variant: 'primary', state: 'loading', children: 'Processing' },
};
 
export const DestructiveDisabled = {
  args: { variant: 'destructive', state: 'disabled', children: 'Delete' },
};

# Design Decisions
 
## 2026-03-27: oklch Color Space Adoption
 
**Judgment**: Use oklch instead of HSL/RGB
 
**Rationale**:
- Perceptually uniform (L=0.5 vs L=0.55 looks the same everywhere)
- Scalability (increase lightness, decrease saturation → lighter variant)
- Aligns with print-industry color science (CIELAB)
 
**Alternatives Considered**:
- HSL: color rotation causes unwanted saturation/brightness shifts ✗
- Tailwind defaults: lacks brand character ✗
 
**Impact**: All color definitions, Figma tokens, theme switching
 
---
 
## 2026-03-27: 44px Minimum Button Height
 
**Judgment**: All interactive elements ≥44px
 
**Rationale**:
- WCAG 2.5.5 recommendation for accessible touch targets
- Includes elderly users, low-dexterity users, touch-pen environments
- Reduces mis-taps by 30% empirically
 
**Exceptions**: None. Even inline buttons get 44px min in mobile context.
 
**Rollout**: Phased. New components first, then legacy migration.