AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Color Shades Generator Agent Guide

Agent guide for generating color shades and tints from a base hex color.

AGENTS.md

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

Project overview

This guide covers src/tools/color-shades-generator/index.ts. The tool parses hex input, normalizes the base color, generates N steps toward black for shades and N steps toward white for tints, and returns the base plus derived arrays without including the base in either array.

Primary source files

  • src/tools/color-shades-generator/index.ts defines meta, private hex parsing, rgbToHex, mix, ShadesResult, and generateShades.
  • src/tools/color-shades-generator/index.test.ts covers invalid input, base normalization, shorthand expansion, counts, hex output, progressive darkening and lightening, black base, and white base.
  • src/tools/color-shades-generator/Body.astro owns browser controls.
  • src/tools/color-shades-generator/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.
  • Normalize base to six-digit lowercase hex.
  • Do not include base color in shades or tints arrays.
  • Generate steps using i divided by n plus one, not endpoints.
  • Keep shades moving toward black and tints moving toward white.
  • Validate behavior for black and white bases.
  • If alpha support is added, define blending behavior explicitly.

Testing

Test invalid input, shorthand input, base normalization, custom counts, valid hex outputs, monotonic channel movement, black base, white base, and alpha behavior if added.

PR checklist

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