Classicy

Previously Platinum

A UI framework using native CSS/JS replications of the Mac OS 8 interface components.

Just curious? Visit our website to learn more.

Demo

See a demo here!

UI Components

See our Storybook collection here!

Using Classicy in a Vite app

Classicy is two packages: @classicy/classicy, the framework, and @classicy/appearance-platinum, the Platinum look. Install both, at the same version:

pnpm add @classicy/classicy @classicy/appearance-platinum
pnpm add react react-dom # for a new app

Import Platinum once, at your app's entry, before you render. The framework registers no Appearance Package of its own:

import "@classicy/appearance-platinum";
import {
  ClassicyAppManagerProvider,
  ClassicyDesktop,
} from "@classicy/classicy";
import { createRoot } from "react-dom/client";

createRoot(document.getElementById("root")!).render(
  <ClassicyAppManagerProvider>
    <ClassicyDesktop>{/* your ClassicyApp components */}</ClassicyDesktop>
  </ClassicyAppManagerProvider>,
);

Without that import, ClassicyDesktop draws a "No Appearance Package is loaded" message (showing the import line) instead of the desktop, mounts none of its children, and logs one error per page. The desktop appears as soon as a package registers. Platinum's own names (PLATINUM_APPEARANCE_PACKAGE_ID, platinumAppearanceHooks, platinumSoundPack) are exports of @classicy/appearance-platinum, which ships its type declarations (bundler, node16 and nodenext resolution).

Browser support: Chrome/Edge 120+, Safari 16.2+, Firefox 113+. Theme colors are mixed in CSS with color-mix() (Safari 16.2, Firefox 113), and icons are drawn with unprefixed mask-image and mask compositing (Chrome 120); in an older browser those declarations are dropped, so tints, overlays and icon art go missing.

Upgrading from 2.1.x? docs/RELEASE-NOTES-APPEARANCE-PACKAGES.md lists every breaking change below, and the rest of the release, with its migration step.

Upgrading from 3.0.x? docs/RELEASE-NOTES-3.1.md: the screen savers (and their logo registry) now ship with @classicy/appearance-platinum; a host importing one from @classicy/classicy changes the import specifier.

Breaking change: the package is renamed. classicy is now @classicy/classicy (the unscoped name stops at 2.x). Replace the dependency, and rewrite every specifier, strings included: from "classicy", deep paths (classicy/dist/classicy.css, classicy/scss/*), vi.mock("classicy", …) and typeof import("classicy"). A host that auto-bumps dependencies (Renovate, a script, pnpm's minimumReleaseAgeExclude) must list both package names and move them together. The scoped names exist from 3.0.0 on; a lower range does not resolve. The release notes give a one-pass sed.

Importing @classicy/classicy injects its stylesheet. Platinum's fonts, art, wallpapers and sound sprites are files in @classicy/appearance-platinum's dist/assets/. Breaking change for Vite consumers: Vite's dev server pre-bundles dependencies into node_modules/.vite/deps/, which breaks those file URLs (they return the SPA fallback page). Exclude both packages from the pre-bundle:

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    exclude: ["@classicy/classicy", "@classicy/appearance-platinum"],
  },
})

Any CommonJS dependency they pull in may then need to go in optimizeDeps.include. Bundlers that handle new URL(…, import.meta.url) (a Vite production build, webpack 5, Rollup with a URL plugin) need no setting; with any other (plain esbuild, Rollup without such a plugin), copy the Platinum package's dist/assets/ next to your bundle. import "@classicy/classicy/fonts" is now a deprecated no-op (the Platinum package registers its fonts), and classicy/dist/fonts.css is gone: a strict-CSP host links @classicy/appearance-platinum/classicy-platinum.fonts.css in its place (below).

Breaking change: system art and cursors are no longer icons. The ClassicyIcons constant is now only the Platinum icon tree as shipped: it does not reflect later registerClassicyIcons calls (ClassicyIcons.myApp.icon is undefined at runtime), so read icons through useClassicyAsset (in a component) or resolveClassicyAsset (elsewhere), never the constant. In particular, registerClassicyIcons({ applications: { ...ClassicyIcons.applications, mine } }) followed by a read of ClassicyIcons.applications.mine now returns undefined (usually behind a cast, so tsc is silent): drop the spread and read through the value registerClassicyIcons returns, or resolveClassicyAsset("icons", "applications.mine"). And Platinum draws these as system art and cursors, so registering them under registerClassicyIcons no longer changes what is drawn (most of them are gone from the icon tree, below). Register the replacement instead:

Icon path you used to register	Register now
system.alias	registerClassicySystemArt("platinum", { aliasBadge })
system.apple	registerClassicySystemArt("platinum", { appleMenu })
system.desktop.trashEmpty	registerClassicySystemArt("platinum", { trashEmpty })
system.desktop.trashFull	registerClassicySystemArt("platinum", { trashFull })
ui.helpButton	registerClassicySystemArt("platinum", { helpButton })
classicy.logo	registerClassicySystemArt("platinum", { aboutLogo })
system.macosSvg	registerClassicySystemArt("platinum", { startupLogo })
ui.cursors.watch, .hand, .resizeLr, .resizeUd, .resizeU, .resizeD, .resizeL, .resizeR	registerClassicyCursors("platinum", { watch, hand, resizeLr, resizeUd, resizeU, resizeD, resizeL, resizeR })

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗