AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Color Name Finder Agent Guide

Agent guide for nearest CSS named color matching by RGB distance.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Color Name Finder in the alexandrai-tools project.

Project overview

This guide covers src/tools/color-name-finder/index.ts. The tool stores a curated CSS named-color table, parses hex input, computes Euclidean RGB distance to every named color, and returns the closest name, exact hex, rounded distance, and exact-match flag.

Primary source files

  • src/tools/color-name-finder/index.ts defines meta, NamedColor, NAMED_COLORS, private hex parsing, ColorNameResult, and findColorName.
  • src/tools/color-name-finder/index.test.ts covers invalid hex, exact primary matches, near match behavior, shorthand hex, output hex format, non-empty name, and non-negative distance.
  • src/tools/color-name-finder/Body.astro owns browser input and display.
  • src/tools/color-name-finder/i18n.ts owns localized copy.
  • src/lib/tools.ts registers metadata.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Return null for invalid hex or empty input.
  • Support shorthand and full hex input.
  • Use Euclidean distance in RGB space consistently.
  • Keep distance rounded for display but choose best match from unrounded distance.
  • Keep exact true only when distance is zero.
  • Do not imply the subset is the complete CSS named-color set unless it is expanded and tested.
  • When adding names, keep hex and RGB values synchronized.

Testing

Test invalid inputs, exact matches, near matches, shorthand expansion, output hex format, distance rounding, tie behavior if relevant, and coverage for newly added named colors.

PR checklist

  • npm test passes for color-name-finder.
  • Pure string or color logic stays independent from DOM preview code.
  • Generated CSS remains copy-ready.
  • Browser-local behavior is preserved.