design-pro-max

Design skills for AI coding agents, one skill per design:

• apple: a router for Apple-platform work that sends each task to one bundled guide, either a third-party part or one of the project's own, and has the agent read that guide in full.
• design-spacing-rhythm: spacing, alignment and vertical rhythm for generated UI and documents, bundled from buidangminh23/spacing-skill.
• icons-pro-max: an icon catalog with the exact brand logos, UI icons and render rules, bundled from buidangminh23/icons-pro-max.

The two bundled skills are copied byte for byte from the latest release of their own repositories and kept in step by a daily job; see Bundled skills.

Status: pre-release. Nothing has been released yet; main already installs as described below.

Install

Install the apple skill folder into a skill root that your agent host reads:

npx skills add buidangminh23/design-pro-max --skill apple -g

The bundled skills install the same way, one --skill per skill:

npx skills add buidangminh23/design-pro-max --skill design-spacing-rhythm -g
npx skills add buidangminh23/design-pro-max --skill icons-pro-max -g

From v0.1 each release also ships design-pro-max-vX.Y.Z.zip with SHA256SUMS.txt. The ZIP holds skills/apple with its hidden .vendor/ folder, which must be copied along with the rest, and the bundled skills next to it.

• A bundled skill is the same skill its own repository releases. Install it from one place only: a machine that already installs spacing-skill or icons-pro-max from their repositories would list the skill twice.

• Install only into a host's own skill roots, such as ~/.claude/skills/ for Claude Code or a user or repository skill folder of Codex. Hosts skip dot-folders there, so they list apple and each bundled skill you installed, and the 38 parts under .vendor/ stay hidden.

• Never run npx skills with --full-depth: it enters dot-folders and installs every part under .vendor/ as a skill of its own.

• Do not put the skill in a Codex executor environment's skill root, such as one of a remote or sandboxed executor: those roots include hidden folders, so every part would register as a skill.

• Use one install channel per machine. Installing with npx skills and copying the release into another skill root makes a host list apple twice.

• With a very large skill library a host may list apple without its description, so it will not start on its own; invoke it as /apple in Claude Code or $apple in Codex.

Layout

skills/
  apple/
    SKILL.md                 router: standing rules, routing table, parts index
    NOTICE.md                disclaimer, trademarks and the icon's source
    references/parts-index.md  generated: every part's group, activation, prerequisites and errata pointers
    agents/openai.yaml       display name and icon for Codex
    assets/apple.svg         the skill icon (the Apple logo)
    shared/                  the checker runtime the project's own parts share: report contract, MP4 reader, media check, test server
    launch-scroll/           own part: pinned and scroll-scrubbed scenes on web pages
      PART.md                the guide the router sends to
      references/            engines and geometry, scrub video, frame sequences, gates, generated evidence
      assets/lib/            scene progress, seek queue and scrub loader, with their CSS contract
      assets/reference/      three reference pages: JavaScript engine, CSS engine, scrub video
      scripts/               probe-scene.mjs (browser checks), encode-scrub.mjs (scrub encoder)
    hig/                     own part: Apple's Human Interface Guidelines for native app interfaces
      PART.md                how to read, build to and review against the guidelines
      references/            own-words digest of every guideline page by section, with generated evidence
    .vendor/                 third-party parts, byte-for-byte at pinned commits
      <part>/
        SKILL.md ...         upstream files, unmodified
        LICENSE              the upstream licence
        UPSTREAM.json        source, commit, prerequisites, risks, errata, Apple text, file hashes and modes
      xcode-build/<part>/
      app-store-connect/<part>/
  design-spacing-rhythm/     bundled: spacing-skill's skill folder at its release tag, plus its LICENSE
  icons-pro-max/             bundled: icons-pro-max's skill folder at its release tag, logos included, plus its LICENSE
skills.json                  generated: the skills in this repository, for installers
vendor/sources.json          the 38 parts: repository, commit, path, excludes, status
vendor/bundles.json          the bundled skills: repository, release tag, commit, licence and every file's hash
scripts/bundle-sync.mjs      sync, check and update for the bundled skills
scripts/lib/bundles.mjs      the bundle record, its checks and BUNDLED_MEDIA, the only bundles that may ship images
scripts/vendor-sync.mjs      sync, check, notices, and stage, classify, confirm and apply for upstream updates
scripts/vendor-guard.mjs     offline guard
scripts/gen.mjs              writes skills.json, the parts index, the README credits and the trademark line
scripts/check-history.mjs    keeps unreviewed images and vendored agents/ and assets/ files out of git history
scripts/release.mjs          checks, packs and verifies the release ZIP; bumps versions and card stats; pushes the tag
scripts/ci-local.mjs         runs the CI steps and the verify run locally when Actions cannot run
scripts/lint-ip.mjs          IP and privacy lint over the project's own files
scripts/verify.mjs           runs every own-part fixture through the checkers, red first
scripts/import-findings.mjs  checks the evidence ledger's source hashes against a research folder
rules.json                   the own parts' rules: level, evidence, check, fixtures and the checker that implements each
evidence/ledger.json         own-words claims with their label, source and source hash
evidence/ip-hashes.json      salted hashes of the private identifiers, private terms and Apple text corpus
designs/apple.json           the apple skill's design record: marks, never-ship list, phrase gates, newest released OS
fixtures/                    pass and fail cases for every error rule, with pages; media is built at run time
evals/                       routing and part evals, the harness that runs them on Claude Code and Codex, and RESULTS.md
.github/workflows/           CI, release, the weekly vendor sync and the own-part verify run
THIRD_PARTY_NOTICES.md       generated credits with every licence text
CONTRIBUTING.md              issues first, MIT-only sources, how a part is added

Why .vendor is hidden

Agent hosts register every SKILL.md they find. Codex scans skill folders recursively but skips dot-directories, and Claude Code registers only the direct children of a skills folder. With every vendored part inside the hidden .vendor/ folder, both hosts list apple as one skill, while every vendored file stays byte-identical to upstream: nothing is renamed or edited to hide them.

The same constraint shapes the rest of the tree: each skill's own skills/<name>/SKILL.md is the only SKILL.md outside dot-directories, there are no symlinks, no .claude-plugin or .codex-plugin folder sits inside skills/apple, no folder is named .claude, .agents, .codex or .git, and no file is named metadata.json, which some installers drop. .gitattributes marks skills/apple/.vendor/** and the bundled skill folders as -text, so git never rewrites vendored or bundled line endings.

Parts

The router reads a part's SKILL.md in full, resolves each relative path a part mentions against the folder of the file that mentions it (then the part's own folder), checks inactive parts' activation first, and applies the errata recorded in its UPSTREAM.json.

Own parts (2)

Written for this project and released under its MIT licence. Each has a PART.md guide; a part with checkers has error rules in rules.json that they enforce, and a pass and a fail fixture for every error rule.

Known limit, measured in evals/RESULTS.md: asked for a scroll-scrub film in AV1 or HEVC only, Codex reads the part's rule and still delivers those codecs alone, recommending H.264 only in its advice; Claude Code adds the H.264 source. Check the delivered <source> list with skills/apple/shared/check-media.mjs before shipping.

The checkers print one JSON line per finding and a summary that states what they prove and what they do not. They exit 0 when every check passes, 1 on an error, 2 when an argument or a tool is missing, and 3 when a sandbox blocks the browser or ffmpeg. They load Playwright from the project passed with --project, never install anything, and never fetch third-party pages.

Vendored, active (6)

Vendored, inactive until their prerequisites exist (32)

An inactive part stays in the tree in full. The router runs its activation check first and stops with the missing prerequisites when the check fails.

Main risks, all gated by the router: the build parts run xcodebuild clean and can delete a passed DerivedData folder; the App Store Connect parts can upload, submit for review, change prices, spend money on Apple Ads, revoke certificates or open a public pull request, so the router shows the exact command and waits for an explicit yes before any of these, sets ASC_TELEMETRY_DISABLED=1 before running asc, and never runs asc install-skills. Every part's prerequisites, risks and errata are listed in vendor/sources.json and in its UPSTREAM.json.

Bundled skills

Whole skills that the owner releases from their own repositories, shipped here unchanged so one install brings them along. vendor/bundles.json pins each to a release tag and its commit and records every file's size and hash; nothing in a bundled folder is edited here.

• node scripts/bundle-sync.mjs sync fetches each pinned commit, proves that the release tag still points at it, and copies the skill folder with the repository's licence as LICENSE. It refuses symlinks, submodules, unsafe names, git metadata, metadata.json, a second visible SKILL.md, and any image, font, media file or archive except the images BUNDLED_MEDIA in scripts/lib/bundles.mjs allows: .svg and .png files under icons-pro-max's assets/ folder.
• The history check and the release check accept a bundled image only with the bytes vendor/bundles.json records for it at the same commit, so a logo changed by hand fails like any unreviewed image.
• The Bundle sync workflow moves each bundle to its repository's latest release; to move one by hand, run node scripts/bundle-sync.mjs update --only <name>, then gen, notices and the checks.

Credits

Every vendored part is MIT-licensed and every vendored file is unmodified. The excludes in vendor/sources.json leave out a nested plugin copy, a plugin manifest, agent UI metadata (agents/openai.yaml) and icon images, some of which reproduce Apple's Swift logo, so no vendored image ships; the images in a release are the apple skill's own icon, skills/apple/assets/apple.svg, whose drawing is devicon's (MIT, licence in skills/apple/NOTICE.md and THIRD_PARTY_NOTICES.md), and the brand logos of the bundled icons-pro-max skill (see Bundled skills). Short passages that a part quotes from Apple, such as a sentence of Apple documentation, WWDC session titles, a few phrases or a short code listing, belong to Apple and are not covered by the MIT licences; each part lists the known ones, with their sources, under appleText in its UPSTREAM.json. Thanks to the authors. Full licence texts are in THIRD_PARTY_NOTICES.md.

Maintenance

Node 22 or later; no dependencies.

To change a pin, edit vendor/sources.json, run sync, check, notices, gen and the guard, and review the upstream diff before committing.

Workflows

• CI (.github/workflows/ci.yml) runs on pushes to main, on pull requests and by hand, on Ubuntu, macOS and Windows with Node 22 and 24: the tests, vendor-sync.mjs check, bundle-sync.mjs check, the guard, notices --check, gen.mjs --check, check-history.mjs, release.mjs check and release.mjs pack.
• Verify (.github/workflows/verify.yml) runs on Ubuntu with ffmpeg and Playwright's headless Chromium, on pushes to main and pull requests that touch the shared runtime, an own part, rules.json, the evidence or the fixtures, on every vX.Y.Z tag and by hand: node scripts/verify.mjs, every fixture judged red first.
• Release (.github/workflows/release.yml) runs when a vX.Y.Z tag is pushed, or by hand for an existing tag, one run at a time. The tag's commit must be on main. It runs every check again and packs the ZIP, creates a draft release with the ZIP and SHA256SUMS.txt, removes any other asset from the draft, downloads both again and verifies them, then publishes the release as Latest and waits until releases/latest points to it. It never publishes a prerelease, because installers read releases/latest, and it leaves a draft unpublished when a newer version is already published, so Latest never moves back. A tag that is already published is only verified: its download is checked against the tag's tree, not compared byte for byte with a rebuild.
• Badges (.github/workflows/badges.yml) runs every six hours and by hand. It renders the view badge with BADGE_SOURCES=views and commits it to the badges branch, which holds only badge SVGs and is never merged; the README reads the badge from there. Without the ANALYTICS_TOKEN secret it publishes nothing and the last badge stays.
• Bundle sync (.github/workflows/bundle-sync.yml) runs every day at 03:17 UTC and by hand. It moves each bundled skill to the latest release of its repository, regenerates the generated files, runs every check, commits to the bundle-sync branch, checks a clean worktree of that commit, pushes the branch with a token scoped to that one step, opens or updates one pull request, starts CI on it and merges it once CI passes on its head commit and main has not moved. When no repository published a newer release it ends after the first step.
• Vendor sync (.github/workflows/vendor-sync.yml) runs on Mondays at 02:41 UTC and by hand. A read-only job stages every source whose upstream HEAD moved past its pin, applies the update to a throwaway checkout, runs the guard and uploads the staged folder. A second job confirms the staged files against upstream, classifies the update, applies it, regenerates the notices and the generated files, runs every check, commits to the vendor-sync branch, checks a clean worktree of that commit, pushes the branch with a token scoped to that one step and opens or updates one pull request from it, never a fork's. It then starts the CI workflow on the branch, because pull requests and pushes made with the workflow's token start no workflow themselves. A safe update, one that changes no shipped file, merges only after that CI run passes on the pull request's head commit and while main has not moved; a needs-review update gets the needs-review label and waits for the owner. When the branch already holds the update, the next run reuses it, so a safe update that could not merge is tried again. A blocked source fails the run and stays at its pin. After 45 quiet days on main the workflow enables itself again through the API, which may not reset GitHub's 60-day timer, and opens an issue; it never pushes to main. The workflow needs the repository setting that lets GitHub Actions create pull requests. If main gets branch protection with required CI checks, the CI run the workflow starts reports those checks on the pull request's head commit, which is where required checks are read; this has not been tried on GitHub yet.

To release: run node scripts/release.mjs bump X.Y.Z, move the [Unreleased] notes into a dated ## [X.Y.Z] - YYYY-MM-DD entry, remove the pre-release banner from this README, run node scripts/release.mjs check vX.Y.Z, commit and push main, wait until CI passes on that commit, then run node scripts/release.mjs push-tag vX.Y.Z.

Exclude globs in vendor/sources.json are matched against paths inside the part and anchored at the part's folder, unlike gitignore patterns: agents/** leaves out the top-level agents folder only, and **/__pycache__ matches at any depth. A pattern that matches a folder leaves out everything in it, and a trailing slash is ignored.

To record Apple text that a part quotes, add an entry to the part's appleText list in vendor/sources.json with the file, the lines ("12", "12-14" or "12, 30"), the source and the reason, then run sync.

Disclaimers

• design-pro-max is an independent open-source project and has not been authorized, sponsored, or otherwise approved by Apple Inc.
• design-pro-max is unrelated to nextlevelbuilder/ui-ux-pro-max.
• The apple skill's icon, skills/apple/assets/apple.svg, is the Apple logo, a trademark of Apple Inc. It identifies the skill's subject only, is not covered by the MIT License, and must not be modified, recolored or redrawn. The drawing comes from devicon (MIT) via buidangminh23/icons-pro-max. It will be replaced with a neutral icon if Apple asks.
• The bundled icons-pro-max skill ships third-party brand marks under skills/icons-pro-max/assets/ (payment networks, social and app logos, technology logos, AI provider marks and connector icons). They belong to their owners, are not covered by any MIT licence, and must not be modified, recolored or redrawn; skills/icons-pro-max/LICENSE says so.
• The vendored parts are their authors' work and are shipped as published. Known errors are recorded as errata in each part's UPSTREAM.json rather than edited in place.

Apple, the Apple logo, iOS, iPadOS, macOS, watchOS, tvOS, visionOS, iPhone, iPad, Mac, Apple Watch, Safari, Siri, Swift, SwiftUI, Xcode, TestFlight, App Store, AirPlay, Apple Pay, Apple Pencil, Apple TV, Apple Vision Pro, CarPlay, CareKit, Digital Crown, Dynamic Island, Face ID, FaceTime, HealthKit, HomeKit, iCloud, iMessage, Live Photos, Mac Catalyst, ResearchKit, SharePlay, Spotlight, Touch ID, SF Symbols, Apple Wallet, Live Activities, Handoff, Multi-Touch, Finder, Mission Control and Apple Music are trademarks of Apple Inc., registered in the U.S. and other countries and regions. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license.

License

The project's own files are released under the MIT License, except the Apple logo at skills/apple/assets/apple.svg (see Disclaimers). Each vendored part keeps its upstream MIT licence in its own LICENSE file, and each bundled skill keeps its repository's licence in skills/<name>/LICENSE; the brand marks in skills/icons-pro-max/assets/ are excluded from it, as that file states.