Skip to content

AGENTS.md

Latest commit

 

History

History
61 lines (41 loc) · 2.73 KB

AGENTS.md

File metadata and controls

61 lines (41 loc) · 2.73 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

VS Code file icon theme extension that uses Octicons, Codicons, and Lucide fonts. Three theme variants are generated from a shared data-driven configuration. All source is plain JavaScript (CommonJS) with no bundler.

Commands

npm run build        # Generate theme JSON files into theme/
npm test             # Build + run AVA tests
npm run lint         # Biome check + validate items (scripts/check-items.js)
npm run lint:fix     # Auto-fix linting issues with Biome

Run a single test file: npx ava tests/themes.test.js

Architecture

Theme Generation Pipeline

scripts/generate-theme.js          Entry point — iterates package.json iconThemes
  └─ src/themes.js                 generateIconTheme() builds and writes each theme
       ├─ src/utils.js             getExpandedItems() expands template patterns in items.json
       ├─ src/data/items.json      Icon definitions: fileExtensions, fileNames, languageIds, iconDefinitions
       ├─ src/data/colors.json     8-color palette (@blue, @cyan, @gray, @green, @magenta, @orange, @red, @violet, @yellow)
       ├─ src/iconmaps/{id}.json   Remap icon names between fonts (e.g. codicons "edit" ← octicons "pencil")
       └─ src/fonts/{id}.json      Font face configuration

Output: theme/unfancy-octicons.icon-theme.json, theme/unfancy-codicons.icon-theme.json, and theme/unfancy-lucide.icon-theme.json

Data Model (items.json)

Icon categories (e.g. src, data, config) map to arrays of file extensions or file names. Templates expand patterns using ${name} placeholders:

{ "names": ["spec", "test"], "templates": ["${name}.js", "${name}.tsx"] }

Each category has an iconDefinitions entry specifying iconColor (color name from colors.json) and iconName (glyph name from codepoints).

Light Theme

Light theme variants are auto-generated by darkening dark theme colors by 40% (Color.darken(0.4)). Icon names get a _light suffix.

Validation

  • src/warnings.js — checks for duplicate extensions and unused icon definitions
  • scripts/check-items.js — runs validation as part of npm run lint
  • tests/items.test.js — validates all color names, icon names, iconmap entries, and category references exist
  • tests/themes.test.js — validates generated theme files have consistent iconDefinitions

Design Rules

  • Only Octicons, Codicons, and Lucide glyphs
  • Color scheme: green=source, yellow=header/template/stylesheet, violet=data, orange=scripts, cyan=docs, blue=media, magenta=ignore/lock, gray=other
  • Generic icons preferred over file-type-specific ones (Ruby is the exception)