Auric Artisan Plugins Developer Reference

The plugins suite is not a monorepo package with one shared runtime. Each host has its own entry point and packaging model. The design goal is behavior parity rather than build-system centralization: every surface exposes WCAG and APCA contrast, practical color parsing, accessible palette support or vision simulation in the way its host expects.

Prefer small, host-native changes. If a feature must span multiple plugins, update the shared parser and color math ports consistently and document any platform-specific deviations.

The suite uses parallel color helper ports rather than importing a single browser module into every host. Keep these contracts aligned when changing math or parsing.

• Accepted inputs: HEX, RGB, RGBA, HSL, HSLA and CSS named colors.
• Core outputs: normalized HEX, RGB, HSL, nearest CSS name, WCAG ratio and APCA Lc.
• Design plugins also use Lab lightness walks for auto-fix behavior.
• Vision simulation uses protanopia, deuteranopia, tritanopia and achromatopsia matrices in design-tool contexts.
• Large document scanning is capped in VS Code with MAX_DOC_BYTES = 1024 * 1024.

Important helper files include plugins/alfred/lib/color-math.js, plugins/vscode/lib/color-core.js, plugins/raycast/src/lib/color-math.ts, plugins/bots/src/lib/color-parse.js, plugins/figma/lib/palette.js and plugins/sketch/.../shared.js.

Figma and Penpot share the same user-facing panel structure: Audit, Palette, Fix and Vision. Their host scripts differ because Figma uses figma.* APIs and Penpot uses penpot.* APIs.

Both hosts compute effective backgrounds by walking ancestors. Figma audits text plus selected fill/stroke UI pairs, while Penpot v1 focuses on text contrast and palette/fix operations for selected shapes.

Preserve message names when refactoring UI code. Existing handlers are direct string switches, so a renamed message silently breaks a panel action.

The Sketch bundle lives under plugins/sketch/Auric Artisan.sketchplugin/Contents/Sketch/. The manifest declares identifier com.auricartisan.sketch, version 0.1.0, compatible version 94 and four menu commands.

Sketch commands are native-dialog oriented. Avoid introducing web UI assumptions into this bundle unless the host packaging and review flow are updated.

plugins/vscode/package.json declares auric-artisan version 0.13.2, “Auric Artisan — Color, Accessibility & Code Health”, for VS Code ^1.74.0. The extension is plain CommonJS with extension.js as its entry and runs without a build step. It activates on the auricArtisanIssues view and on CSS-family files plus JS, TS, React, HTML, Vue, Svelte, Astro, PHP, JSON, JSONC, Markdown and XML.

• hoverProvider parses the color token under the cursor and returns a MarkdownString with a data-URI swatch, values, nearest name and contrast tables.
• colorProvider supplies VS Code's native color picker for non-CSS languages that lack VS Code's built-in color picker, when colorPicker.mode is decorators or the native hover picker is on.
• extractPairs() in lib/scanner.js scans each style scope for color, background-color and an opaque, non-gradient background.
• analyzeDocument() writes diagnostics under collection auric-artisan with code low-contrast. Documents over MAX_DOC_BYTES = 1024 * 1024 are skipped.
• The activity bar container auricArtisan holds three views: Overview (webview auricArtisanHome), Accessibility Issues (tree auricArtisanIssues) and Color Picker (webview auricArtisanPickerView, collapsed).
• Keybindings: Ctrl+Alt+C / Cmd+Alt+C runs auricArtisan.pickColor and Ctrl+Alt+A / Cmd+Alt+A runs auricArtisan.inspectAccessibility, both when the editor has focus.
• Workspace data goes to .auric-artisan/ (auricArtisan.data.folderName): scan-cache.json, settings.json, the health record and the remediation plan.

The 23 commands:

The 46 settings:

Scripts in plugins/vscode/package.json: npm test runs test/run-tests.js and test/build.test.js; npm run validate runs test/validate.mjs; npm run verify runs both the validator and the tests, as does vscode:prepublish; npm run package builds the VSIX with vsce.

The CLI takes --json, --sarif, --baseline, --write-baseline, --fail-on high|medium|low, --max-new, --min-score, --profile, --threshold, --no-code-health, --max-files (default 20000) and --quiet, honours .auricignore, and exits 0 on a pass, 1 on a policy violation and 2 on a usage error.

npm run build (or npm run vscode:build at the repository root) runs build/build.mjs, which writes four extensions to dist/<app>/: auric-color, auric-a11y, auric-codehealth and auric-artisan, an Extension Pack that ships no code and installs the other three. Each build rewrites the auricArtisan namespace into its own, for example auricA11y.scanProject, because two installed extensions cannot own the same command or setting id. The CHANGELOG lists this split as 1.0.0, unreleased; 0.13.2 ships as the single extension above.

Keep diagnostic parsing deliberately conservative. False positives in source files become noisy very quickly, especially in generated CSS, theme files and documentation examples.

Alfred uses info.plist to wire the aa contrast script filter to /usr/bin/env node contrast.js "$1". The script emits Alfred-shaped JSON { items } to stdout.

• splitArgs() supports quoted segments and function-style colors with spaces.
• Rows include ratio, APCA Lc, foreground HEX, background HEX and a full summary.
• Modifier metadata lets users copy a full summary from the ratio row.
• pack.ps1 and pack.sh build Auric Artisan.alfredworkflow.

cd plugins/alfred
./pack.sh

Raycast is a TypeScript React command package. package.json declares the contrast command in view mode with required foreground and background text arguments.

• src/contrast.tsx renders Detail with markdown preview, metadata rows and copy actions.
• Dependencies are @raycast/api and @raycast/utils.
• Scripts include ray develop, ray build -e dist, ray lint and ray publish.
• Color helper ports live under src/lib/.

cd plugins/raycast
npm run dev
npm run build
npm run lint

plugins/bots/src/index.js is the Worker entry. It routes Slack, Discord, social preview, social publish, X account checks, robots.txt, security.txt and health checks, and its scheduled handler runs the daily post.

Discord command registration is handled by register-discord-commands.js. It creates command aa-contrast with one required string option named colors.

The social publisher reads /js/components/color-of-the-day.js, extracts the public palette arrays, derives the mega palette, selects the daily color with date/time-zone logic and formats the social post.

• colorSourceUrl() defaults to https://auricartisan.com plus the public color component path.
• getColorOfTheDayFromSource() parses source text and computes the daily color.
• buildColorOfTheDayPost() writes the public post body, RGB, HSL, explore URL and hashtags.
• collectTargets() supports Slack webhook, Discord webhook, Mastodon, X and generic JSON webhook targets.
• postColorOfTheDay() supports dry runs, enable gating, per-target posting and failure collection.

The cron expression in wrangler.toml is 30 3 * * *. Cloudflare runs cron in UTC, so this corresponds to 09:00 in Asia/Kolkata.

wrangler.toml sets the non-secret values under [vars]: SOCIAL_POST_ENABLED = "0", SOCIAL_POST_DRY_RUN = "1", SOCIAL_POST_HASHTAGS, AURIC_BASE_URL, COLOR_OF_DAY_SOURCE_URL, COLOR_OF_DAY_TIME_ZONE and X_EXPECTED_USERNAME, so posting is off as committed. Everything else is a secret, uploaded with wrangler secret put or npm run x:secrets.

Figma and Penpot are source-folder plugins. Validate manifests and host loading directly before publishing or distributing store packages.

• Figma declares networkAccess.allowedDomains = ["none"]; keep design-file work local unless product requirements change.
• Penpot write permission is needed for outlines, fixes and palette application. Avoid widening permissions without release notes.
• Slack rejects unsigned or stale requests using HMAC-SHA256 verification and a five-minute replay window.
• Discord rejects unsigned interactions using Ed25519 verification over timestamp plus body.
• Social publishing requires SOCIAL_POST_SECRET for manual posts and SOCIAL_POST_ENABLED=1 for non-dry-run publishing.
• Generated design outlines should be removable and named with stable Auric Artisan prefixes.
• Do not add remote code execution paths to plugin UIs. Keep scripts local to the package.

• Parse every JSON manifest and package file in plugins/.
• Verify Figma menu commands: audit, palette, fix and vision.
• Verify Penpot permissions and UI script references.
• Verify Sketch manifest command identifiers and referenced scripts.
• Run Alfred contrast with HEX, RGB, HSL and named color inputs.
• Run Raycast build and lint when changing TypeScript or package metadata.
• Run VS Code hover, color provider and CSS-family diagnostics in representative files.
• Run bot tests and verify Slack and Discord signature paths with known test requests.
• Preview Color of the Day before enabling social publishing.
• Regenerate documentation discovery, feeds, sitemaps, PWA cache and search after docs changes.

node scripts/generate-discovery.mjs
node scripts/generate-pwa-cache-manifest.mjs
node search/client/build-index.js
npm test

For platform workflow instructions, see the Plugins User Guide.