
package com.smartgwt.client.docs;

/**
 * <h3>Color Overview</h3>
 * <h3>Color Spaces</h3> Smart GWT's {@link com.smartgwt.client.util.Colors} class works in three
 * color spaces, each with different strengths. All three are always available on every {@link
 * com.smartgwt.client.util.Color} object - conversion is automatic. <ul> <li><b>RGB</b> ({@link
 * com.smartgwt.client.util.Color#getR Color.r}, {@link com.smartgwt.client.util.Color#getG
 * Color.g}, {@link com.smartgwt.client.util.Color#getB Color.b}) - the hardware color space.    
 * Each channel is 0-255. Best for: direct pixel-level work, matching exact hex values, and    
 * interop with legacy APIs. Poor for manipulation - "add 20 to green" is not a meaningful    
 * perceptual operation. <li><b>HSL</b> ({@link com.smartgwt.client.util.Color#getH Color.h},
 * {@link com.smartgwt.client.util.Color#getS Color.s}, {@link com.smartgwt.client.util.Color#getL
 * Color.l}) - separates hue (color),     saturation (intensity), and lightness. Hue is 0-360
 * degrees, s and l are 0-100. Intuitive     for humans but <i>not</i> perceptually uniform - 50%
 * lightness in yellow looks far brighter     than 50% lightness in blue. <li><b>oklch</b> ({@link
 * com.smartgwt.client.util.Color#getOk_L Color.ok_L}, {@link
 * com.smartgwt.client.util.Color#getOk_C Color.ok_C}, {@link
 * com.smartgwt.client.util.Color#getOk_h Color.ok_h}) - a perceptually     uniform color space
 * where equal numeric steps produce equal perceived visual differences.     L is 0-1 (lightness),
 * C is ~0-0.4 (chroma/saturation), h is 0-360 (hue). Best for: color     manipulation, palette
 * generation, accessibility contrast checking. All     {@link
 * com.smartgwt.client.util.Colors#adjust adjust()} operations work in oklch. Note that oklch hue
 * angles differ     from HSL hue angles (red is ~30 in oklch vs 0 in HSL) because oklch
 * redistributes hues for     perceptual uniformity. </ul> <h3>Color Formats and Conversion</h3>
 * The {@link com.smartgwt.client.types.ColorFormat} type covers four CSS string representations:
 * <code>"hex"</code>, <code>"rgb"</code>, <code>"hsl"</code>, and <code>"oklch"</code>. Key
 * conversion methods: <ul> <li>{@link com.smartgwt.client.util.Colors#getColor Colors.getColor()}
 * - parse any color string or object into a full {@link com.smartgwt.client.util.Color} with    
 * all three color spaces pre-computed <li>{@link com.smartgwt.client.util.Colors#getString
 * Colors.getString()} - convert to a CSS string in any format <li>{@link
 * com.smartgwt.client.util.Colors#getValues Colors.getValues()} - extract raw numeric components
 * in one color space <li>{@link com.smartgwt.client.util.Colors#isColor Colors.isColor()} -
 * validate without conversion <li>{@link com.smartgwt.client.util.Colors#getFormat
 * Colors.getFormat()} - detect the format of a color string </ul> {@link
 * com.smartgwt.client.util.Colors#getColor Colors.getColor()} always returns a Color object
 * (never null). If the input cannot be parsed, {@link com.smartgwt.client.util.Color#isValid
 * isValid()} returns false and properties default to black. <h3>Color Manipulation</h3> All
 * manipulation methods operate in oklch for perceptual uniformity and return new Color objects or
 * CSS strings. <ul> <li>{@link com.smartgwt.client.util.Colors#adjust Colors.adjust()} -
 * general-purpose multi-axis adjustment (lightness, saturation,     hue, alpha); the foundation
 * for all other manipulation methods <li>{@link com.smartgwt.client.util.Colors#lighten
 * Colors.lighten()} / {@link com.smartgwt.client.util.Colors#darken Colors.darken()} - perceptual
 * lightness (oklch L) <li>{@link com.smartgwt.client.util.Colors#brighten Colors.brighten()} /
 * {@link com.smartgwt.client.util.Colors#dim Colors.dim()} - combined lightness + chroma
 * boost/cut <li>{@link com.smartgwt.client.util.Colors#saturate Colors.saturate()} / {@link
 * com.smartgwt.client.util.Colors#desaturate Colors.desaturate()} - chroma (oklch C) <li>{@link
 * com.smartgwt.client.util.Colors#complement Colors.complement()} / {@link
 * com.smartgwt.client.util.Colors#spin Colors.spin()} - hue rotation <li>{@link
 * com.smartgwt.client.util.Colors#flatten Colors.flatten()} - composite semi-transparent color to
 * opaque over a background <li>{@link com.smartgwt.client.util.Colors#getAlpha Colors.getAlpha()}
 * / {@link com.smartgwt.client.util.Colors#setAlpha Colors.setAlpha()} - read or change the alpha
 * channel </ul> <h3>Inspection</h3> <ul> <li>{@link com.smartgwt.client.util.Colors#isDark
 * Colors.isDark()} - perceptual light-vs-dark test (oklch L &lt; 0.6) <li>{@link
 * com.smartgwt.client.util.Colors#contrast Colors.contrast()} - approximate perceptual contrast
 * ratio between two colors <li>{@link com.smartgwt.client.util.Colors#distance Colors.distance()}
 * - perceptual color difference in oklab space <li>{@link com.smartgwt.client.util.Colors#equals
 * Colors.equals()} - same-color comparison across formats </ul> <h3>CSS Color Relationships</h3>
 * Modern CSS supports <i>derived colors</i> - colors defined as transformations of a base color
 * using CSS Relative Color Syntax (RCS). For example, a skin might define a "hover highlight" as
 * "10% lighter than the accent color": <code>oklch(from var(--accent) calc(l + 0.10) c h)</code>.
 * When the user changes the accent color, the hover highlight updates automatically because it is
 * defined as a <i>relationship</i> rather than a fixed hex value. <P> Four methods form a
 * pipeline for working with these color relationships: <ul> <li>{@link
 * com.smartgwt.client.util.Colors#resolveCSS Colors.resolveCSS()} - resolve any CSS color
 * expression (including     <code>var()</code> references) to a flat Color via the browser's CSS
 * engine <li>{@link com.smartgwt.client.util.Colors#parseRelationship Colors.parseRelationship()}
 * - extract the structure of an RCS expression (origin,     color space, channel deltas) without
 * evaluating it <li>{@link com.smartgwt.client.util.Colors#describeRelationship
 * Colors.describeRelationship()} - given a base and derived color, compute what     changed (e.g.
 * "lightened by 0.15 in oklch") <li>{@link com.smartgwt.client.util.Colors#generateCSS
 * Colors.generateCSS()} - produce an oklch RCS expression from a relationship     descriptor,
 * ready for CSS output </ul> <b>Typical round-trip</b>: a skin config stores <code>oklch(from
 * var(--accent) calc(l + 0.15) c h)</code>. On load, <code>parseRelationship()</code> extracts
 * the origin and deltas. The Skin Editor resolves <code>var(--accent)</code> via
 * <code>resolveCSS()</code> to show a color swatch. If the user changes the accent,
 * <code>generateCSS()</code> rebuilds the RCS expression with the same relationship but the new
 * origin. <P> {@link com.smartgwt.client.util.Colors#getColor Colors.getColor()} can also resolve
 * RCS expressions with literal color origins (hex, named colors, rgb()/hsl()/oklch() calls) in
 * pure JavaScript - no DOM required. For expressions that reference CSS custom properties via
 * <code>var()</code>, {@link com.smartgwt.client.util.Colors#resolveCSS Colors.resolveCSS()} is
 * needed to resolve them through the browser's CSS engine. <P> Channel ranges in RCS follow the
 * native CSS scale for each color space: r/g/b are 0-255, h is degrees, s/l are 0-100 (HSL), and
 * oklch L is 0-1, C is ~0-0.4, h is 0-360. Each channel position in the RCS expression can be a
 * bare keyword (<code>r</code>), a <code>calc()</code> expression (<code>calc(r - 50)</code>), or
 * a <code>max()</code>/<code>min()</code> wrapper for clamping (<code>max(calc(s - 80),
 * 0)</code>). <h3>Palette and Harmony</h3> Methods for generating sets of related colors: <ul>
 * <li>{@link com.smartgwt.client.util.Colors#colorScale Colors.colorScale()} - multi-step
 * gradient between two endpoints <li>{@link com.smartgwt.client.util.Colors#mix Colors.mix()} -
 * blend two colors at a given ratio <li>{@link com.smartgwt.client.util.Colors#mostReadable
 * Colors.mostReadable()} - pick the highest-contrast candidate against a background <li>{@link
 * com.smartgwt.client.util.Colors#triad Colors.triad()} / {@link
 * com.smartgwt.client.util.Colors#tetrad Colors.tetrad()} - evenly-spaced hues around the color
 * wheel <li>{@link com.smartgwt.client.util.Colors#splitComplement Colors.splitComplement()} -
 * flanking the complementary hue <li>{@link com.smartgwt.client.util.Colors#analogous
 * Colors.analogous()} - nearby hues for harmonious palettes </ul> All interpolation and palette
 * methods default to oklch for perceptual uniformity. <h3>Theme Generation</h3> Higher-level
 * methods for generating color themes from one or a few seed colors. These handle sRGB gamut
 * mapping automatically - oklch can represent colors outside the displayable range, but all
 * returned colors are gamut-safe. <ul> <li>{@link com.smartgwt.client.util.Colors#palette
 * Colors.palette()} - generate a tonal ramp (dark-to-light series) from a seed     color, with
 * professional chroma curves, hue shift, and automatic gamut mapping <li>{@link
 * com.smartgwt.client.util.Colors#scheme Colors.scheme()} - generate harmonious seed colors from
 * one primary (e.g.     split-complementary, triadic), with chroma subordination for visual
 * hierarchy <li>{@link com.smartgwt.client.util.Colors#autoContrast Colors.autoContrast()} - find
 * a WCAG-compliant text color for any background,     with optional hue tinting for a polished
 * look </ul> Typical workflow: <code>scheme()</code> picks harmonious seed colors, then
 * <code>palette()</code> generates a tonal ramp for each seed.
 * @see com.smartgwt.client.util.Colors#autoContrast
 * @see com.smartgwt.client.util.Colors#palette
 * @see com.smartgwt.client.util.Colors#scheme
 * @see com.smartgwt.client.util.Colors#resolveCSS
 * @see com.smartgwt.client.util.Colors#parseRelationship
 * @see com.smartgwt.client.util.Colors#describeRelationship
 * @see com.smartgwt.client.util.Colors#generateCSS
 */
public interface ColorOverview {
}
