Taster

진단부품톤 고르기
부품 갤러리 / Appearance picker

Appearance picker

Form and input

Three radio cards for light, dark and system on the settings page, each showing a small screen drawn with the real tokens, for services where the mode matters.

내 사이트에서 가져오기

색을 고르면 아래 부품이 그 색으로 바뀝니다.

실제로 돌아가는 부품입니다. 눌러 보고 입력해 보세요.

내 앱에 넣기

  1. 아직 npm 패키지가 없어서 Taster 리포를 받아 그 안의 명령을 씁니다. 내 앱 폴더가 들어 있는 폴더에서 한 번만 받습니다.

    git clone https://github.com/makim-414/taster.git && npm ci --prefix taster/packages/engine
  2. 내 앱 폴더에서 이 부품을 넣습니다. 부품 파일과 토큰 파일이 src/components/taster 에 들어갑니다.

    node ../taster/packages/engine/cli.mjs add blocks/appearance-picker --from https://taster-six.vercel.app --dir src/components/taster
  3. 부품은 Tailwind 클래스로 그리고, Taster 프리셋이 그 클래스를 토큰에 연결합니다. Tailwind CSS 를 설치하고, tokens.css 를 앱 루트에서 한 번 불러온 뒤, 앱 루트에 이 설정을 둡니다. 프리셋이 없으면 빌드는 되어도 부품이 스타일 없이 나옵니다.

    // tailwind.config.cjs
    module.exports = {
      presets: [require('./src/components/taster/tailwind-preset.cjs')],
      content: ['./index.html', './src/**/*.{ts,tsx}'],
    };

    Tailwind v3 는 이 파일을 그대로 읽습니다. v4 는 Tailwind 를 불러오는 src/ 의 스타일시트 맨 위에 이 두 줄을 넣습니다.

    @import "tailwindcss";
    @config "../tailwind.config.cjs";

    tokens.css 는 :root 에 --bg, --text, --border, --accent 를 정의합니다. 내 앱의 스타일시트가 같은 이름을 뒤에서 다시 정의하면 그쪽 색이 이깁니다. 새 Vite 앱의 스타터 CSS 처럼 그런 변수가 있으면 지우거나 이름을 바꾸세요.

언제 쓰나요

  • Appearance pickerThree radio cards for light, dark and system on the settings page, each showing a small screen drawn with the real tokens, for services where the mode matters.
  • Token themesRaw values, roles and component tokens in three layers with one brand variable on top, and both light and dark defined as token sets with a switch. Dark steps by gray levels, not neon glow.

대신 없애 주는 AI 티

  • Dark only, no light mode (CMP-11)
  • Same large radius and same soft shadow on everything (CMP-04)
  • Cream background with a terracotta accent (COL-02)
  • Near-black background with a neon glow (COL-03)
  • Green as the replacement for banned purple (COL-05)
  • Text that does not stand out from its background (COL-08)

정보

설치할 패키지
tailwindcss
라이선스
MIT
출처
Written for this registry; idea from Campsite ThemePicker via 21st.dev, https://github.com/campsite/campsite, CC BY-NC 4.0 (no code taken)
코드 보기
import * as React from 'react'
import { cn } from './_cn'
import { useStyleOnce } from '../motion/_motion'

// Appearance picker: three radio cards (light, dark, system), each showing a small screen drawn with the real tokens,
// so the previews follow the brand. For services where the mode matters enough to sit on a settings page. This is the
// component for patterns/appearance-picker.md.
// Written for this registry after a 21st.dev "Theme Toggle" the owner picked, which comes from Campsite's ThemePicker.
// Campsite is CC BY-NC 4.0, which does not fit an MIT registry or commercial use, so no code or SVG was taken. Left out
// on purpose: next-themes and framer-motion as requirements, the blue ring, the fixed hex previews, and returning null
// until mount, which made the section jump in.
// Needs tokens.css and themes/light.css.

export type Appearance = 'light' | 'dark' | 'system'

const DEFAULT_KEY = 'theme'
const DEFAULT_LABELS: Record<Appearance, string> = { light: 'Light', dark: 'Dark', system: 'System' }
const OPTIONS: Appearance[] = ['light', 'dark', 'system']

export interface AppearancePickerProps extends Omit<React.FieldsetHTMLAttributes<HTMLFieldSetElement>, 'onChange' | 'defaultValue'> {
  /** Controlled value. With it, the caller applies the mode (for example with next-themes). */
  value?: Appearance
  /** First value when uncontrolled and nothing is stored. Default system. */
  defaultValue?: Appearance
  onValueChange?: (value: Appearance) => void
  /** localStorage key when uncontrolled. Default theme. */
  storageKey?: string
  /** Group name, read by screen readers and shown above the cards. Default Theme. */
  legend?: React.ReactNode
  /** Labels per option, for other languages. */
  labels?: Partial<Record<Appearance, string>>
}

const CSS = `
.ds-appr{border:0;margin:0;padding:0;min-width:0}
.ds-appr-legend{padding:0;margin-bottom:var(--sp-3);font-size:var(--t-body);font-weight:var(--w-med);color:var(--text)}
.ds-appr-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:var(--sp-3)}
.ds-appr-opt{position:relative;display:block;cursor:pointer}
.ds-appr-opt input{position:absolute;inset:0;z-index:1;width:100%;height:100%;margin:0;opacity:0;cursor:pointer}
.ds-appr-frame{position:relative;display:block;aspect-ratio:4/3;overflow:hidden;border-radius:var(--r-md);outline:1px solid var(--border);outline-offset:0;transition:outline-color var(--dur-dropdown) var(--ease-out)}
.ds-appr-opt:hover .ds-appr-frame{outline-color:var(--text-subtle)}
.ds-appr-opt input:checked~.ds-appr-frame{outline:2px solid var(--brand);outline-offset:2px}
.ds-appr-opt input:focus-visible~.ds-appr-frame{outline:2px solid var(--ring);outline-offset:4px}
.ds-appr-name{display:block;margin-top:var(--sp-3);font-size:var(--t-sm);color:var(--text-muted);text-align:center}
.ds-appr-opt input:checked~.ds-appr-name{font-weight:var(--w-semi);color:var(--text)}
.ds-appr-mock{position:absolute;inset:0;display:grid;grid-template-columns:28% 1fr;background:var(--bg)}
.ds-appr-mock.theme-dark{color-scheme:dark}
.ds-appr-mock[data-half]{clip-path:polygon(100% 0,100% 100%,0 100%)}
.ds-appr-side{display:flex;flex-direction:column;gap:8%;padding:12% 10%;background:var(--bg-sunken)}
.ds-appr-main{display:flex;flex-direction:column;gap:6%;padding:9% 10%}
.ds-appr-bar{display:block;height:5%;min-height:2px;border-radius:var(--r-sm);background:var(--text-subtle)}
.ds-appr-side .ds-appr-bar{height:8%;background:var(--border)}
.ds-appr-head{width:45%;background:var(--text)}
.ds-appr-panel{display:block;flex:1;border-radius:var(--r-sm);background:var(--bg-sunken)}
`

function Screen({ mode, half }: { mode: 'light' | 'dark'; half?: boolean }) {
  return (
    <span className={cn('ds-appr-mock', mode === 'light' ? 'theme-light' : 'theme-dark')} data-half={half ? '' : undefined}>
      <span className="ds-appr-side">
        <span className="ds-appr-bar" />
        <span className="ds-appr-bar" />
        <span className="ds-appr-bar" />
      </span>
      <span className="ds-appr-main">
        <span className="ds-appr-bar ds-appr-head" />
        <span className="ds-appr-bar" />
        <span className="ds-appr-panel" />
      </span>
    </span>
  )
}

function systemMode(): 'light' | 'dark' {
  return window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark'
}

/** Writes the mode on <html>. System resolves to what the device asks for now. */
export function applyAppearance(value: Appearance) {
  document.documentElement.setAttribute('data-theme', value === 'system' ? systemMode() : value)
}

/** Put this in an inline script in <head>, so a stored mode is on the page before the first paint. */
export function appearanceInitScript(storageKey: string = DEFAULT_KEY) {
  // A JSON string is a valid JS string literal. Writing every < as \u003c keeps a key like "</script>" from closing the tag.
  const key = JSON.stringify(storageKey).replace(/</g, '\\u003c')
  return `(function(){try{var s=localStorage.getItem(${key});var t=s==='light'||s==='dark'?s:matchMedia('(prefers-color-scheme: light)').matches?'light':'dark';document.documentElement.setAttribute('data-theme',t)}catch(e){}})()`
}

function isAppearance(v: string | null): v is Appearance {
  return v === 'light' || v === 'dark' || v === 'system'
}

export function AppearancePicker({
  value, defaultValue = 'system', onValueChange, storageKey = DEFAULT_KEY, legend = 'Theme', labels, className, ...rest
}: AppearancePickerProps) {
  useStyleOnce('ds-appr', CSS)
  const name = React.useId()
  const controlled = value !== undefined
  const [inner, setInner] = React.useState<Appearance>(defaultValue)
  const current = controlled ? value : inner

  // The server cannot read storage, so the stored choice arrives after mount. The cards keep their space meanwhile.
  React.useEffect(() => {
    if (controlled) return
    let stored: string | null = null
    try { stored = localStorage.getItem(storageKey) } catch { /* storage blocked: the choice lasts for this page only */ }
    if (!isAppearance(stored)) return
    setInner(stored)
    applyAppearance(stored)
  }, [controlled, storageKey])

  // While on system, follow the device when it changes.
  React.useEffect(() => {
    if (controlled || current !== 'system') return
    const media = window.matchMedia('(prefers-color-scheme: light)')
    const follow = () => applyAppearance('system')
    media.addEventListener('change', follow)
    return () => media.removeEventListener('change', follow)
  }, [controlled, current])

  function choose(next: Appearance) {
    if (!controlled) {
      setInner(next)
      try { localStorage.setItem(storageKey, next) } catch { /* see above */ }
      applyAppearance(next)
    }
    onValueChange?.(next)
  }

  return (
    <fieldset className={cn('ds-appr', className)} {...rest}>
      <legend className="ds-appr-legend">{legend}</legend>
      <div className="ds-appr-grid">
        {OPTIONS.map((option) => (
          <label key={option} className="ds-appr-opt">
            <input type="radio" name={name} value={option} checked={current === option} onChange={() => choose(option)} />
            <span className="ds-appr-frame" aria-hidden="true">
              <Screen mode={option === 'dark' ? 'dark' : 'light'} />
              {option === 'system' && <Screen mode="dark" half />}
            </span>
            <span className="ds-appr-name">{labels?.[option] ?? DEFAULT_LABELS[option]}</span>
          </label>
        ))}
      </div>
    </fieldset>
  )
}