A UI framework using native CSS/JS replications of the Mac OS 8 interface components.
Just curious? Visit our website to learn more.
Classicy is a framework, @classicy/classicy, and the looks it draws, its
Appearance Packages: @classicy/appearance-platinum, the Platinum look (Mac
OS 8), and @classicy/appearance-system7, System 7 (below). Install the
framework and a package, at the same version:
pnpm add @classicy/classicy @classicy/appearance-platinum
pnpm add react react-dom # for a new appImport 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.
Upgrading from 3.4.x? docs/RELEASE-NOTES-3.5.md: the new System 7 package, and the core capabilities it brought (per-theme asset variants, 16 px icon images, alert sounds from the sound pack, Classicy's own scroll bars); ClassicyControlGroup no longer paints its title's background inline.
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 every Classicy package
it loads (@classicy/classicy, @classicy/appearance-platinum and, when you
load it, @classicy/appearance-system7) and move them together. The core and
Platinum exist from 3.0.0 on, System 7 from 3.5.0; 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 (and @classicy/appearance-system7, when you load it, as
example/vite.config.ts does):
// vite.config.ts
export default defineConfig({
optimizeDeps: {
exclude: [
"@classicy/classicy",
"@classicy/appearance-platinum",
"@classicy/appearance-system7", // when you load it
],
},
})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
each package's dist/assets/ (Platinum's, and System 7's when you load it)
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 }) |
Seven icon paths are gone from ClassicyIcons and the Platinum icon tree.
Nothing in Classicy drew any of them; register your own image under a path to
keep it (registerClassicyIcons({ system: { bomb } }); the 2.1.7 images are in
that release's assets/img/):
| Removed icon path | Replacement |
|---|---|
system.bomb |
None |
system.files._229, system.files._232Messages |
None (their files never existed: both were "" in 2.1.x) |
ui.halftoneSmall |
None (Classicy's halftone is the system art halftone, a different image) |
ui.menuDropdownArrows |
System art popupArrows (the same arrows, in currentColor) |
ui.stripe |
None (a diagonal hatch; the title-bar stripes, system art windowStripes, are a different pattern) |
ui.tab |
Nearest: system art tabOutline (the same shape as an open outline, not filled) |
Thirteen more icon paths are gone in 3.0: their files were Platinum's alone,
and moved into the Platinum package. Read what Platinum registers in their
place, the same image (useClassicyAsset or resolveClassicyAsset):
| Removed icon path | Read instead |
|---|---|
system.apple |
system art appleMenu |
system.alias |
system art aliasBadge |
system.desktop.trashEmpty, system.desktop.trashFull |
system art trashEmpty, trashFull |
ui.helpButton |
system art helpButton |
ui.cursors.watch, .resizeLr, .resizeUd, .resizeU, .resizeD, .resizeL, .resizeR |
the cursor role of the same name |
controlPanels.appearanceManager.platinum |
the Platinum package's icon (getClassicyAppearancePackage("platinum")?.icon) |
ui.cursors.add, eyedropper, handCounting, highlight, menu, plus, precision, rom, shortcut, spin |
None (the files were unread and are deleted; register your own at the path with registerClassicyIcons to keep one) |
docs/AGENT-REFERENCE.md §5 has the full asset-registry reference.
Breaking change: shared state classes and cascade layers. A component's
state is now a bare class beside its root class, so the classes that folded a
state into their name are gone, and data-state is no longer set anywhere.
Update host CSS and tests that select them:
| Old class | Now |
|---|---|
classicyWindowActive, classicyWindowInactive |
.classicyWindow.active, .classicyWindow.inactive |
classicyWindowCollapsed, classicyWindowDragging |
.classicyWindow.collapsed, .classicyWindow.dragging |
classicyButtonDefault, classicyButtonDepressed |
.classicyButton.default, .classicyButton.pressed |
classicyMenuItemDisabled, classicyMenuItemOpen |
.classicyMenuItem.disabled, .classicyMenuItem.open |
classicyTabButtonActive |
.classicyTabButton.selected |
classicyDesktopIconActive, classicyDesktopIconOpen, classicyDesktopIconActiveAndOpen |
.classicyDesktopIcon.selected, .open, .selected.open |
classicyIconActive |
.classicyIcon.selected |
classicyListBoxOptionSelected, classicyTableRowSelected |
.classicyListBoxOption.selected, .classicyTableRow.selected |
classicyDesktopMenuAppleMenu |
classicyDesktopMenuApple |
[data-state="…"] on BevelButton, Placard, ImageWell |
.checked, .pressed, .mixed, .disabled, .selected, .open |
The exported type ClassicyBevelButtonState is deleted. @classicy/classicy/scss/* now
resolves to the vocabulary (@use "@classicy/classicy/scss/vocabulary"); the old theme
partials are Platinum's, at @classicy/appearance-platinum/scss/* (see
Appearance Packages below). The global .hidden
utility and classicyWindowZoomed are gone, and a zIndex passed in style
to ClassicyWindow, ClassicyIcon or ClassicyDesktopIcon is dropped.
Classicy's stylesheet is now in cascade layers
(@layer classicy.base, classicy.package, classicy.user), so unlayered host
CSS and every host layer beat Classicy whatever the specificity: a host
button { … } or Tailwind v4's Preflight now restyles Classicy's controls.
Keep resets in the reserved classicy.base.host sublayer (for Tailwind v4,
replace @import "tailwindcss"; with the granular form in
docs/AGENT-REFERENCE.md §1). Because the state classes are bare generic
names (active, open, error, selected, …), a host's global
.active { … } now matches Classicy elements too: scope such rules to your
own markup. The screen saver's hidden cursor no longer beats an unlayered host
* { cursor: … }.
The full old → new table (every renamed class) is in docs/AGENT-REFERENCE.md
§5, "Migrating to the shared vocabulary". Markup you build by hand to look like
Classicy's needs the same vocabulary: the bare state classes, plus
data-classicy-part on menu-bar clusters and data-classicy-control on
title-bar boxes, which flex order now keys on (without them a zoom box sorts
left of the title).
Breaking change: the look is an Appearance Package. Classicy's stylesheet
now holds structure only; the Platinum look (every bevel, border, gradient
and piece of art) is the Platinum Appearance Package's own stylesheet, in
@layer classicy.package and scoped under
.classicyDesktop[data-classicy-appearance="platinum"]. Importing
@classicy/appearance-platinum registers it, and everything inside
ClassicyDesktop looks as before.
-
Components outside a desktop get structure only, no look. Wrap a standalone component in an element carrying
class="classicyDesktop"anddata-classicy-appearance="platinum", with the theme and asset variables on it (getThemeVars(getTheme("default"))anduseClassicyAssetVars()); give itid="classicyDesktop"so portals (menus, balloons) render inside it rather than falling back, unstyled, todocument.body. -
Strict-CSP hosts link three files, first in
<head>and in this order:@classicy/classicy/dist/classicy.css(structure, the core's), then the Platinum package's@classicy/appearance-platinum/classicy-platinum.css(the look) and@classicy/appearance-platinum/classicy-platinum.fonts.css(the Platinum fonts). Those are the packages'exports; a plain<link>names the files themselves:<link rel="stylesheet" href="/node_modules/@classicy/classicy/dist/classicy.css"> <link rel="stylesheet" href="/node_modules/@classicy/appearance-platinum/dist/classicy-platinum.css"> <link rel="stylesheet" href="/node_modules/@classicy/appearance-platinum/dist/classicy-platinum.fonts.css">
A policy that blocks inline
<style>blocks all three runtime injections; the fonts file holds the same@font-facerules the package writes, each pointing at its.woff2in the Platinum package'sdist/assets/(serve that folder beside it, and allow it infont-src). Allowdata:inimg-srctoo (img-src 'self' data:): a dimmed icon (a hidden application's in the Application menu, a disabled list row's) is drawn on a canvas and shown from adata:URL, and a few masks and glyphs are inlinedata:images, which a policy without it shows broken. Link the files rather than importing them through your bundler: Vite inlines the small Monaco font as adata:URL, whichfont-src 'self'blocks. If you must import them, setbuild.assetsInlineLimit: 0or allowfont-src data:. Linking (copied, or served fromnode_modules) is the recommended way. -
The theme partials moved.
classicy/scss/appearance,classicy/scss/scrollbarsandclassicy/scss/assets(2.1.x; pre-release builds called themclassicy/scss-platinum/*) are now@classicy/appearance-platinum/scss/mixins,…/scrollbarsand…/assets. The mixins are renamed to kebab-case with aplatinum-prefix (appearance.platinumWindowControlBoxBorder→mixins.platinum-window-control-box-border;scrollbars.scrollbars→scrollbars.platinum-scrollbars), exceptscrollbars.scrollbars-inactive, which is removed (it never drew in Classicy's own windows; copy its rules from the 2.1.7 source if you used it), andpx-rect/no-selectmoved to the vocabulary asclassicy-px-rect/classicy-no-select(@classicy/classicy/scss/layout). The full rename table is indocs/AGENT-REFERENCE.md, "Migrating to Appearance Packages".classicy/scss/themes.jsonis gone: callgetAllThemes(). Platinum's partials reach the vocabulary aspkg:@classicy/classicy/scss/*, so a host that@uses them compiles with Sass'sNodePackageImporter(Vite:css.preprocessorOptions.scss.importers: [new NodePackageImporter()]), imported from the Sass package your build uses:sass-embeddedfor a host onsass-embedded,sassfor one onsass.@classicy/classicy/appearance/platinumand@classicy/classicy/appearance/platinum/scss/*are gone: import@classicy/appearance-platinum, which registers Platinum and exports its names (PLATINUM_APPEARANCE_PACKAGE_ID,platinumAppearanceHooks,platinumSoundPack), which are no longer@classicy/classicyexports. -
platinum-halftonetakes a token name. The mixin now takes a color token NAME (@include mixins.platinum-halftone("--color-black"), not a color) and paints the dither on a::beforechild, which setsposition: relativeandisolation: isolateon the element it is included in. Theencode-colorSCSS function is removed. -
Platinum's art is registered system art (
--classicy-art-<key>, published byClassicyDesktop): theassets.$…art variables are gone, and a standalone component needsuseClassicyAssetVars()on its wrapper (above) or its art is missing.ClassicyWindowFramenow draws the window's title bar (ClassicyWindowTitleBar): target.classicyWindowFrame .classicyWindowTitleBarinstead of the removedclassicyWindowFrameTitleBar/classicyWindowFrameTitleText. The Control Strip and pop-up slider row constants (controlStripTab,popUpSliderTrack, …) are no longer exported: read them withuseClassicyPixelArtRows(key)or draw<ClassicyPixelArt art={key} />. The publishedplatinum-window-control-boxandplatinum-window-control-box-depressablemixins draw their dither from--classicy-art-window-dither, so a host using them outside a desktop must define it (or accept no dither). They andplatinum-menu-dividernow draw only the look: the box's size and its::before/::aftergeometry, and the divider's full-width stretch, are base structure, so a host including them on an element of its own sets those itself. -
Text glyphs are package CSS. The menu check and dash, the pop-up and combo-box check, the bevel button's ▸ ▾, the placard's ▾, the file input's ✕ and the HyperCard tools palette's ✓ are now empty
aria-hiddenspans the package fills with::before/::aftercontent: theirtextContentis"", andgetByText("✓")finds nothing. -
Checkable roles. A menu item with
checkedset isrole="menuitemcheckbox"witharia-checked, sogetByRole("menuitem", { name })misses it; a HyperCard tools-palette entry isrole="button"witharia-pressed. -
Caption colors are custom properties. A
captionStylereaches the cue as--classicy-caption-*properties, not inlinecolorandbackground-color(style.colorreads""), so it no longer carries inline precedence: host CSS inclassicy.user, or unlayered, overrides it. Theme captions through.quickTimePlayerCaptions:not(.quickTimePlayerCaptionsCustomStyle)to keep the viewer's choice. -
ClassicyKbdwraps each modifier in its own<span class="classicyKbdModifier" data-classicy-part="modifier-<name>">. The text is unchanged; snapshots of its children change. -
Fixed: Firefox no longer shows a scroll bar under tab strips in the built library (the desktop's scroll-bar fallback used to beat the tab scroller's
scrollbar-width: none).
The full mixin table and the package API are in docs/AGENT-REFERENCE.md
§5, "Migrating to Appearance Packages", and §8, "Appearance Packages".
Changed: sizes and colors derive from the theme.
- Overriding an input no longer rescales the derived sizes. Stylesheets
read named sizes that
getThemeVarscomputes from the theme (--menu-min-width,--popup-height,--ui-font-size-small, …) instead ofcalc(var(--window-control-size) * N). A host that overrides an input such as--window-control-sizeon the desktop now changes only that variable. Change the theme's measurement instead, or override the derived variable itself (docs/AGENT-REFERENCE.md§8, "Overriding sizes from a host"). - Error title bars are
#ffcccc,classicy-tint("--color-error", 80%), instead of#f7cecd, so they follow a theme's error color. New SCSS helpersclassicy-tint,classicy-shadeandclassicy-alphaare at@classicy/classicy/scss/color. ClassicyWindowOpenno longer treats[0, 0]as "no position". A new window opens where itspositionsays,[0, 0]included. To have it cascaded (30 + 10·n), omitpositionor passautoPosition: true.ClassicyWindowalways supplies a position, so its windows are unaffected (default[110, 110]).- A package knob that would make a variable Classicy sets itself
(
menu.minWidth→--menu-min-width) is skipped with a warning and left out of the Options tab.
New: Appearance Packages can rename and re-icon apps. A package's
optional apps field ({ "MoviePlayer.app": { name: "Media Player", icon, description } }, keyed by app id, bundled or your own) changes how an app is
shown everywhere its name or icon is drawn. It is display only: ids, action
types, records and persisted state keep the app's own name, and analytics
paths are built from the app id (window titles still reach GA as drawn), so
build nothing from a displayed name, and read
useClassicyAppIdentity(id, { name, icon }) for text that names an app.
Under any package:
- File-system adapters see one snapshot-hash change on the first save after upgrading: the derived Applications, Extensions and Control Strip Modules entries are no longer persisted or sent in snapshots.
- A derived folder never overwrites a static entry. A user's file named
like an app is kept, and the app is listed beside it as " ()";
only Platinum's untouched placeholders (
_placeholder) give way. - App records and desktop icon balloons follow the code.
apps[id].nameandiconare refreshed fromClassicyApp's props on every mount, and a desktop icon's balloon is stored only whendesktopIconBalloonHelpis given (the manifest description is resolved at render). - PDF Viewer's close action type is fixed. It dispatched
"ClassicyAppPDF ViewerCloseFile"(with a space); it now dispatchesClassicyAppPDFViewerCloseFile. A host matching the old string must match the new one. - Every asset
url()is quoted. CSS variables and styles that carry an asset (--classicy-icon-mask,--desktop-background-image, the cursor, …) are writtenurl("…"), so adata:SVG icon keeps its mask. Tests that matched the unquoted string must expect the quotes. - Error alerts are session-only.
Desktop.errorDialogis no longer persisted, so a reload never re-shows an open alert.
Details: docs/AGENT-REFERENCE.md §8, "App display overrides".
Changed: pixel sizes are theme knobs. Platinum looks the same; the
Control Strip, menu frame, Pager, Balloon Help, pop-up slider, dialogs and
the other pixel-matched surfaces now read measurements.<family> knobs from
the theme (--<family>-<key>) instead of Npx literals.
- Breaking:
POPUP_MENU_MAX_HEIGHTis removed. The pop-up menu's cap is the theme variable--menu-pop-up-max-height(300 under Platinum);classicyPopUpMenuPlacementtakes it as an optional last argument. - Breaking: no pixel fallbacks. Stylesheets read
var(--x)with noNpxfallback, so a component outsideClassicyDesktopneeds the fullgetThemeVars(theme)on its wrapper. - Breaking for packages: a measurement whose variable starts with
--color-, or names one of the 119 named derivations, is skipped. - Breaking for host CSS: 84 more sizes are named derivations that
getThemeVarssets, so overriding an input variable such as--window-padding-sizeno longer moves them: change the theme, or override the derived variable. - Breaking for SCSS hosts: Platinum's published
platinum-menu-frameandplatinum-scrollbarsmixins read knob variables that onlygetThemeVarsemits. - The Options tab shows six groups of Platinum knobs.
withDefaultThemeMetrics(theme, defaults?)takes the defaults to fill from; passclassicyThemeMeasurementDefaults(theme.package)to complete a package's families.
Details: docs/AGENT-REFERENCE.md §5, "Upgrading: package knobs and the
pixel-literal purge (Part H)", and §8, "Package knob families".
@classicy/appearance-system7 draws System 7.5, in black and white
("System 7") and in color ("System 7 Color"), with System 7.5's own icons,
art, cursors, desktop pattern and alert sounds, and the same twelve screen
savers. Use it alone or beside Platinum; the Appearance Manager switches
between them. Install every package you load at one version, and bump them
together:
pnpm add @classicy/classicy @classicy/appearance-system7
# or, with both looks:
pnpm add @classicy/classicy @classicy/appearance-platinum @classicy/appearance-system7import "@classicy/appearance-platinum"; // optional
import "@classicy/appearance-system7";A Vite host lists it in optimizeDeps.exclude too (above). Its README,
packages/appearance/system7/README.md,
has its exports and its strict-CSP stylesheets.
This project uses pnpm (enable it with corepack enable). First install dependencies:
pnpm installTo create a production build:
pnpm buildTo create a development build:
pnpm devTo run the example site locally (builds the package and starts the example dev server):
pnpm previewThen visit the site in your browser at http://localhost:3000.
(For iterative package development you can also use pnpm dev, which builds the source. The example/ app consumes it directly through the pnpm workspace — no linking step required.)
The Browser app requires the TimeMachine Web Proxy to fetch archived web pages. A Docker Compose setup is included in the example/ folder:
cd example
cp .env.example .env # adjust if needed
docker compose up -dThe proxy runs on http://localhost:8765 by default. Enable it in the Browser app under File → Settings → Enable TimeMachine Proxy.
- New Dawn by
Nathanael Gentry - Scrollbars of the Classic Mac OS by
Jessica Stokes (@ticky) after-dark-css, for the basic System 7.1.1 interface and screen saversflyer, for further inspiration- Robin Casady, from the legendary Casady & Greene for releasing ChicagoFLF into the public domain
- Apple, who maintains the copyright on the background patterns, icons and interface components
Legend
| ✅ | ℹ️ | |
| Complete | Partially complete. | Experimental |
| Subject to change |
- Desktop
- ✅ The ubiquitous Finder
- Menubar
- ✅ System Menu
- ✅ App Switcher
- ✅ Widgets
- ✅ Date/Time
- ✅ Sound
- Icons
- ✅ App Shortcuts
- ✅ Cleanup
- Arrange By…
- Sounds
- ✅ Sound Provider
- ✅ Load sound theme from JSON
- ✅ Audio Sprites support
- ✅ Sound Manager Control Panel
- ✅ Sound Event Handler
- ✅ Event dispatcher/player
- ✅ Automatic event intercept and play for known events (map audio sprites to events)
- ✅ Sound Event Handler
- Logging & Diagnostics
- ✅
registerClassicyLogSink— host apps receive Classicy logs, errors, and crash reports (production builds included)
- ✅
- Screen Saver
- ✅ Idle-activated full-screen screensavers (After Dark CSS ports: Flying Toasters, Fish, Warp, and 9 more, shipped by
@classicy/appearance-platinum; each Appearance Package offers its own) - ✅ Screen Saver Control Panel (pick saver, timeout, per-saver options)
- ✅
registerClassicyScreenSaverAPI with custom or schema-derived options UI
- ✅ Idle-activated full-screen screensavers (After Dark CSS ports: Flying Toasters, Fish, Warp, and 9 more, shipped by
- Appearance Manager Control Panel (Theme Manager)
- ✅ Appearance Manager Control Panel
- ✅ System
- ✅ Load theme from JSON
- ✅ System events for modifying theme
- UI
- ✅ Typography settings
- ✅ Measurement settings
- ✅ Desktop settings
- ✅ System colors
- ✅ Configurable color variables
- ✅ Color Theme-able components
- App Template
- ✅ App Context/Event Handler
- ✅ App Switcher
- Window
- Controls
- ✅ Zoom
- ✅ Resize
- ✅ Collapse
- ✅ Close
- ✅ Placard
- ✅ Header
- Dialog
- Modal
- Dialog
- ✅ Movable
- ✅ Non-movable
- Alert
- ✅ Movable
- ✅ Non-movable
- Dialog
- ✅ Modeless
- Modal
- ✅ Standard
- Controls
- System
- ✅ File System
- ✅ Integrated into Finder.app
- ✅ File System
- UI Components
- ✅ Text Input
- ✅ Text Area
- ✅ Button
- ✅ Tabs
- ✅ Radio Button
- ✅ Drop-down menu
- ✅ Drop-down menu groups (optgroup)
- ✅ Form (dialog layout, safe submit)
- ✅ Multi-select menu (List Box)
- ✅ Combo box (autocomplete)
- ✅ Table (Platinum list view)
- ✅ Checkbox
- ✅ Bevel Button
- ✅ Slider
- ✅ Spinner
- ✅ Date Picker
- ✅ Time Picker
- ✅ Expandable (Disclosure)
- ✅ Fieldset
- ✅ Separator
- ✅ Progress
- ✅ Balloon Help (tooltip)
- ✅ Link (desktop-routed hyperlink)
- ✅ Meter (gauge with zones)
- ✅ Output (read-only result)
- ✅ Keyboard shortcut display (kbd)
- ✅ Menu
- ✅ Desktop Menu
- ✅ Contextual Menu
- ✅ Submenu
- Gallery Picker (Slider)
- ✅ Color Picker
All components are exported from the @classicy/classicy package. Import them by name:
import { ClassicyWindow, ClassicyButton, ClassicyBalloonHelp } from '@classicy/classicy';Building an app?
docs/BUILDING-APPS.mdis the step-by-step guide:ClassicyAppandClassicyWindowprop-by-prop, manifests, reducers, menus, icons, files, dialogs, balloon help, sound, analytics, extensions, persistence, and testing — plus the traps that cost the most time. It ships with the package atnode_modules/@classicy/classicy/docs/BUILDING-APPS.md.Using an AI coding agent? A complete machine-oriented reference to the public API — every component's props, app/event/icon registration, theming, analytics, sound, and the untrusted-action rules — ships with the package at
docs/AGENT-REFERENCE.md(node_modules/@classicy/classicy/docs/AGENT-REFERENCE.md). Point your agent at it.
Each table below lists the raw HTML element the component replaces — inside a
Classicy desktop, prefer the component over the raw tag (e.g. ClassicyButton
instead of <button>) to get theming, sounds, and balloon help for free. The
full two-way map, including HTML elements that have no Classicy equivalent,
is in docs/AGENT-REFERENCE.md §4.0.
| Component | Description | HTML equivalent |
|---|---|---|
ClassicyDesktop |
Root desktop surface — icons, menu bar, wallpaper, drag-select | — (desktop metaphor) |
ClassicyDesktopMenuBar |
Top menu bar with system menu, app menu, and widget tray | <nav> |
ClassicyApp |
Application container. Props: id, name, icon, defaultWindow |
— |
ClassicyWindow |
Window chrome with title bar and controls. Props: id, appId, title, closable, zoomable, collapsable, resizable, modal, initialSize, initialPosition, minimumSize |
<dialog> (non-modal; modal prop for modal) |
ClassicyBoot |
Boot screen shown on first load | — |
ClassicyScreenSaver |
Idle-activated screensaver extension (auto-mounted by ClassicyDesktop); register your own savers with registerClassicyScreenSaver (packages names the Appearance Packages that offer one) |
— |
ClassicyAboutWindow |
Standard "About This App" dialog. Props: appId, appName, appIcon |
<dialog> |
| Component | Description | HTML equivalent |
|---|---|---|
ClassicyButton |
Push button. Accepts children as label | <button> |
ClassicyCheckbox |
Checkbox with optional label. Props: checked, label, onChangeFunc |
<input type="checkbox"> |
ClassicyRadioInput |
Radio button group. Props: label, options (array of { label, value }) |
<input type="radio"> group |
ClassicyInput |
Single-line text field. Props: placeholder, value, onChangeFunc |
<input type="text"> (any text-like type) |
ClassicySpinner |
Numeric stepper (up/down arrows). Props: value, min, max, step |
<input type="number"> |
ClassicyPopUpMenu |
Drop-down selector. Props: label, options ({ label, value } items or { groupLabel, options } groups), value |
<select> / <option> / <optgroup> |
ClassicyListBox |
Scrolling list with single or multi selection (⌘-toggle, Shift-range). Props: options, selectionMode, selected, onChangeFunc, visibleRows |
<select multiple> |
ClassicyComboBox |
Editable field with filtering suggestions and a pop-up arrow. Props: options, filter, freeText, onSelectFunc |
<datalist> |
ClassicyDatePicker |
Date input with calendar picker. Props: value, placeholder, onChangeFunc |
<input type="date"> |
ClassicyTimePicker |
Time input with clock picker. Props: value, placeholder, onChangeFunc |
<input type="time"> |
| Component | Description | HTML equivalent |
|---|---|---|
ClassicyTextEditor |
Plain-text editor area. Props: content, onChangeFunc |
<textarea> |
ClassicyRichTextEditor |
Rich-text editor (bold, italic, lists). Props: content, onChangeFunc |
contenteditable region |
| Component | Description | HTML equivalent |
|---|---|---|
ClassicyTabs |
Tabbed container. Children must be ClassicyTab items with a title prop |
— (ARIA role="tablist" pattern) |
ClassicyDisclosure |
Collapsible section (expand/collapse). Props: label, open |
<details> / <summary> |
ClassicyControlGroup |
Labeled fieldset grouping form controls. Props: label |
<fieldset> / <legend> |
ClassicyControlLabel |
Inline label for a control. Props: label |
<label> |
ClassicySplitView |
Resizable two- or three-pane container with a draggable, keyboard-accessible divider. Props: direction, defaultSizes, minPaneSize, onResize, onResizeCommit |
— (nearest: obsolete <frameset>) |
ClassicyForm |
Form wrapper with HIG row/dialog spacing; submit never navigates. Props: onSubmitFunc, layout. Pair with ClassicyFormButtonRow for the Cancel/OK row |
<form> |
ClassicyTable |
Platinum list view over arbitrary data: sortable/resizable columns, Mac row selection, keyboard navigation. Props: columns, rows, getRowId, selectionMode, onActivateRow |
<table> |
| Component | Description | HTML equivalent |
|---|---|---|
ClassicyMenu |
Drop-down menu used in the menu bar. Props: id, title, menuChildren |
<menu> |
ClassicyContextualMenu |
Right-click context menu. Renders at pointer position | <menu> (the old contextmenu attribute) |
| Component | Description | HTML equivalent |
|---|---|---|
ClassicyProgressBar |
Determinate progress bar. Props: value, max, label |
<progress> |
ClassicyMeter |
Gauge with native meter zone semantics (theme accent / alert / error). Props: value, low, high, optimum, segments |
<meter> |
ClassicyOutput |
Read-only calculation result — static text or inset well. Props: value, htmlFor, variant |
<output> |
ClassicyKbd |
Keyboard shortcut display in Platinum glyph order (⇧⌘S), inline or as key caps. Props: shortcut, variant |
<kbd> |
ClassicyLink |
Themed hyperlink routed through the desktop URL opener (WebViewer, browser, or new tab). Props: href, disposition, event |
<a> |
ClassicyBalloonHelp |
Mac OS 8-style speech-bubble tooltip. Wraps any element. Props: content, title, position, delay |
title attribute (tooltip) |
ClassicyIcon |
System icon image with optional label. Props: src, label |
<img> + caption |
| Component | Description | HTML equivalent |
|---|---|---|
ClassicyFileBrowser |
File browser with icon and list views. Props: path, onSelect |
— |
| Component | Description | HTML equivalent |
|---|---|---|
QuickTimeMovieEmbed |
Embedded QuickTime-style video player. Props: url |
<video> / <audio> |
| Component | Description | HTML equivalent |
|---|---|---|
ClassicyDesktopMenuWidgetTime |
Clock widget for the menu bar | — |
ClassicyDesktopMenuWidgetSound |
Deprecated. Mute toggle for the menu bar, no longer mounted by default. Use the Control Strip's built-in Sound module instead (classicy-sound; turn it off with ClassicyDesktop's controlStrip={{ disabledModules }}). Still exported; logs a one-time dev warning when mounted |
— |
| Component | Description | HTML equivalent |
|---|---|---|
ClassicyControlStrip |
Mac OS 8 Control Strip at the desktop's lower left, showing every registered module — the built-in Sound and Screen Saver modules plus any an app or extension registers. Mounted by ClassicyDesktop; configure with its controlStrip prop (disabledModules, defaultCollapsed, defaultWidth), or pass false to hide it. Its collapsed state, width, and the user's module choices persist |
role="toolbar" |
registerClassicyControlStripModule |
Adds a module (id, label, 16 px icon, menuItems or content, optional owning appId and order). Call at module scope; the strip updates live. Each module is also listed in System Folder:Control Strip Modules |
— |
ClassicyControlStripManager |
The Control Strip control panel: show or hide the strip, and show, hide or reorder its modules | — |
ClassicyPopUpSlider |
Compact vertical slider for a pop-up bevel button (the Control Strip volume slider). Props: value, onChange, ariaLabel |
<input type="range"> |
<ClassicyAppManagerProvider><ClassicyDesktop><ClassicyDesktopMenuBar><ClassicyDesktopIcon?><YourClassicyApp><ClassicyApp><ClassicyWindow?><ClassicyUIControls?><OtherReactNodes?>
ClassicyDesktop must be imported eagerly. Mounting it lazily, a tick after
ClassicyAppManagerProvider, corrupts manager state: early dispatches reach a
reducer whose state the desktop has not seeded yet, and every dispatch after
that throws.
Writing an app? Start with
docs/BUILDING-APPS.md — a step-by-step guide covering
ClassicyApp, ClassicyWindow, manifests, reducers, menus, files, dialogs,
sound, analytics, persistence, and testing.
ClassicyAppManagerProvider accepts an optional defaultState — a deep-partial
ClassicyStore merged over the built-in defaults on first load only (when no
saved state exists in localStorage). Returning visitors keep their persisted
state.
<ClassicyAppManagerProvider
defaultState={{
System: { Manager: { DateAndTime: {
dateTime: "2001-09-11T12:40:00.000Z", // 8:40 AM US Eastern (EDT, UTC-4)
timeZoneOffset: "-4",
} } },
}}
>
{/* ... */}
</ClassicyAppManagerProvider>Arrays in defaultState replace their default counterparts wholesale (they are
not concatenated). To force a value on every load regardless of saved state,
clear localStorage["classicyDesktopState"] or dispatch the change at runtime.
ClassicyAppManagerProvider accepts optional defaultFileSystem and
defaultFileSystemMode props to seed the virtual filesystem used by Finder
and other file-aware apps on first load only (when no saved filesystem
exists in localStorage["classicyStorage"]). Returning visitors keep their
persisted filesystem.
<ClassicyAppManagerProvider
defaultFileSystem={{
"Macintosh HD": {
_type: "drive",
_icon: ClassicyIcons.system.drives.disk,
Documents: {
_type: "directory",
_icon: ClassicyIcons.system.folders.directory,
"My Document.txt": {
_type: "text_file",
_mimeType: "text/plain",
_data: "Hello, Classicy!",
},
},
},
}}
defaultFileSystemMode="merge"
>
{/* ... */}
</ClassicyAppManagerProvider>defaultFileSystemMode controls how the filesystem is constructed:
"merge"(default) deep-merges your tree onto the library'sDefaultFSContent"exclusive"uses your tree as the entire filesystem, ignoringDefaultFSContent
Like defaultState, filesystem trees are seed-only. To force a filesystem
value on every load regardless of saved state, clear localStorage["classicyStorage"]
or rebuild the filesystem at runtime.
To correct a returning visitor's already-persisted tree — renaming a seeded
file, fixing a bad URL — pass defaultFileSystemSeedMigrations, a list of
one-time corrections applied against stored state (see
ClassicyFileSystemSeedMigrations.ts).
ClassicyDesktop automatically mounts seven built-in apps — SimpleText,
PDFViewer, MoviePlayer, PictureViewer, HyperCard, WebViewer, and
Calculator — the same way it always mounts Finder. Each can be disabled
individually via a prop on ClassicyAppManagerProvider:
<ClassicyAppManagerProvider
disableSimpleText={false} // default: false (loads)
disablePDFViewer={false} // default: false (loads)
disableMoviePlayer={true} // opt out of Movie Player
disablePictureViewer={true} // opt out of Picture Viewer
disableHyperCard={true} // opt out of HyperCard
disableWebViewer={true} // opt out of Web Viewer
disableCalculator={true} // opt out of Calculator
>
<ClassicyDesktop />
</ClassicyAppManagerProvider>A disabled app is also cleared from what a visitor saved before you disabled
it: its Apple-menu entry, its Applications listing and an open window go away
on their next visit. Disabling only stops the app from auto-mounting — it
remains available to import and render yourself (e.g. import { PDFViewer } from "@classicy/classicy") if you want custom placement, and an app you
render yourself keeps its entries.
-
ClassicyDesktopClassicyDesktopClickClassicyDesktopDragClassicyDesktopSetBalloonHelp
-
ClassicySoundPlayClassicyAlertSosumiClassicyAlertWildEepClassicyAlertIndigoClassicyBeepClassicyBootClassicyButtonClickDownClassicyButtonClickUpClassicyInputRadioClickDownClassicyInputRadioClickUpClassicyMenuCloseClassicyMenuItemClickClassicyMenuItemHoverClassicyMenuOpenClassicyWindowCloseClassicyWindowCollapseClassicyWindowControlClickDownClassicyWindowControlClickUpClassicyWindowExpandClassicyWindowFocusClassicyWindowMoveIdleClassicyWindowMoveMovingClassicyWindowMoveStopClassicyWindowOpenClassicyWindowResizeIdleClassicyWindowResizeResizingClassicyWindowResizeStopClassicyWindowZoomMaximizeClassicyWindowZoomMinimize
-
ClassicyDesktopIconClassicyDesktopClickClassicyDesktopAltClickClassicyDesktopDoubleClickClassicyDesktopDrag
-
ClassicyAppClassicyAppOpenClassicyAppCloseClassicyAppHideClassicyAppFocus
-
ClassicyWindowClassicyWindowOpenClassicyWindowCloseClassicyWindowZoomClassicyWindowCollapseClassicyWindowResizeClassicyWindowDragClassicyWindowFocusClassicyWindowContentScrollClassicyWindowContentClick
-
ClassicyMenuClassicyMenuHoverClassicyMenuClickClassicyMenuChange
This software is provided free and in the public domain under The Unlicense.