Class: Tuile::Theme

Inherits:
Object
  • Object
show all
Defined in:
lib/tuile/theme.rb,
sig/tuile.rbs

Overview

A set of semantic colors the built-in components read when painting. The current theme lives at Screen#theme; components must look it up at paint time (inside repaint) rather than caching values, so a Screen#theme= restyles everything via one invalidate-everything pass. Book ch6 is the concept in full (why accents-only, dark/light, live OS flips).

The rendering helpers — #active_bg, #active_border, #input_bg — wrap a plain string in the token's SGR color (on the channel appropriate for the token's role) and reset:

screen.theme.active_bg("[ Ok ]")       # => "\e[48;5;59m[ Ok ]\e[0m"
screen.theme.active_border("┌────┐")   # => "\e[32m┌────┐\e[0m"

Content passes through verbatim (so it may carry other escapes). For span-aware styling — a token applied to a StyledString without flattening its per-span colors — use the *_color readers instead (with_bg(theme.active_bg_color)). Rule of thumb: plain chrome → helper; structured text → *_color reader + StyledString.

Two built-in themes ship: DARK (default) and LIGHT. A custom one is one with away, and every token must be a Color instance — not the lenient Color.coerce forms, since a theme is declared once so the verbosity self-documents:

screen.theme = Theme::DARK.with(active_border_color: Color::CYAN)

App-specific tokens

An app carries its own colors in #custom (frozen Hash{Symbol => Color}). Look them up with #[] (fail-fast on typos) and render with the generic #fg / #bg helpers; subclass for semantic readers (Data#with keeps the subclass). Pair dark/light variants in a ThemeDef for Screen#theme_def=.

theme = Theme::DARK.with(custom: { accent: Color::DARK_ORANGE })
theme[:accent]              # => Color, e.g. for StyledString#with_fg
theme.fg(:accent, "NEW")    # => "\e[38;5;208mNEW\e[0m"

class AppTheme < Tuile::Theme
def accent(text) = fg(:accent, text)
end

For a color slot resolved live at paint — currently Component#bg_color= — assign a Ref instead of reading + rebuilding the token in Component#handle_theme_changed; it tracks theme swaps on its own. Baked content colors (Component::Label text and friends) can't: they live in a frozen StyledString and still need the hook.

Defined Under Namespace

Classes: Ref

Constant Summary collapse

CHROME_TOKENS =

The built-in chrome color tokens — every Data member bar #custom. A Ref resolves a name in this set as the chrome color; anything else as a #custom token.

Returns:

  • (Array<Symbol>) 
(members - %i[custom]).freeze
DARK =

The colors Tuile used before themes existed, tuned for dark terminal backgrounds. GREY37 (palette 59) is what Rainbow emits for :darkslategray; GREY27 (238, ~#444444) sits in the grayscale ramp, bright enough to stand out against non-pure-black dark terminal themes (Gruvbox/Solarized/ OneDark base backgrounds sit in the #1d–#2d range) yet distinctly darker than the active highlight at 59 (~#5f5f5f). The scrollbar reuses GREY37, giving the handle the weight of the selection well and leaving the sparser track glyph near-invisible.

error_color is INDIAN_RED1 (203, ~#ff5f5f) rather than a pure RED1 (196): the message sits beside a field on the terminal's own background, and the softer red keeps its contrast there while pure red vibrates.

The error wells are palette 88 (~#870000) and LIGHT_PINK4 (95, ~#875f5f) — split on lightness the way GREY27/GREY37 are, so the focused one is the lighter well and the pair reads as a well rather than an alarm block. Both survive palette256 as themselves and stay distinct from each other there, which is what keeps focus visible on an invalid field. The focused well stays out of the bright mid-reds around #af5f5f: that is where terminals put the cursor, and a caret sitting in an invalid field blurs into a well of its own color.

placeholder_color is GREY66 (248, ~#a8a8a8): dimmer than the terminal's own foreground, so an empty field's hint reads as absent-value rather than as typed text. It is the dimmest grey that still quantizes to :white on a 16-color terminal — everything below 248 lands on :bright_black alongside both wells, where the hint is not subtle but gone (design/decisions.md D_placeholder).

Returns:

new(active_bg_color: Color::GREY37,
active_border_color: Color::GREEN,
input_bg_color: Color::GREY27,
placeholder_color: Color::GREY66,
error_color: Color::INDIAN_RED1,
error_bg_color: Color.palette(88),
error_active_bg_color: Color::LIGHT_PINK4,
scrollbar_color: Color::GREY37)
LIGHT =

Counterparts legible on light terminal backgrounds: grayscale-ramp highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253 ~#dadada — dark enough to read as a "well" against white, one step lighter than the active highlight). active_border_color stays the named green — named ANSI colors are remapped by the terminal's own palette, so the theme picks a light-appropriate green for us. GREY62 (247, ~#9e9e9e) is the scrollbar: a foreground against pale, so it goes a step darker than the highlights rather than matching them. RED3 (124, ~#af0000) is the error ink, dark for the same reason — the light red DARK uses would wash out on white.

The error wells are MISTY_ROSE1 (224, ~#ffd7d7) and LIGHT_PINK1 (217, ~#ffafaf) — near-white tints that read as a well by hue rather than by weight, and darken on focus as the grey pair does. 224 is the palest red the 256-color palette holds: anything subtler quantizes onto the grey ramp (Color.hex("#ffeaea") → 255) and the signal is gone entirely on a 256-color terminal. It sits a shade above GREY85 rather than below it, so an invalid field reads level with a valid one rather than more recessed — the price of staying close to a white background.

placeholder_color mirrors DARK's rule from the other side: GREY62 (247, ~#9e9e9e) is the palest grey that still quantizes to :bright_black on a 16-color terminal, where both light wells are :white. It doubles as the scrollbar ink, which wants the same thing — a foreground that recedes against pale without vanishing into it.

Returns:

new(active_bg_color: Color::GREY82,
active_border_color: Color::GREEN,
input_bg_color: Color::GREY85,
placeholder_color: Color::GREY62,
error_color: Color::RED3,
error_bg_color: Color::MISTY_ROSE1,
error_active_bg_color: Color::LIGHT_PINK1,
scrollbar_color: Color::GREY62)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:, error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: {}) ⇒ Object

@param active_bg_color

@param active_border_color

@param input_bg_color

@param placeholder_color

@param error_color

@param error_bg_color

@param error_active_bg_color

@param scrollbar_color

@param custom — app-specific tokens, see #custom.



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/tuile/theme.rb', line 114

def initialize(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
               error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: {})
  { active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
    error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color: }.each do |name, value|
    raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
  end
  raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)

  custom.each do |key, value|
    raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
    raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
  end
  super(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
        error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: custom.dup.freeze)
end

Instance Attribute Details

#active_bg_color ⇒ Color (readonly)

Background highlight of the component the user is interacting with: the Component::List cursor row, the focused Component::TextField / Component::TextArea well, the focused Component::Button. "Active" matches the Component#active? focus-chain flag — this is the focus/selection highlight in conventional UI terms.

Returns:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/tuile/theme.rb', line 100

class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color,
                          :placeholder_color, :error_color, :error_bg_color, :error_active_bg_color,
                          :scrollbar_color, :custom)
  # @param active_bg_color [Color]
  # @param active_border_color [Color]
  # @param input_bg_color [Color]
  # @param placeholder_color [Color]
  # @param error_color [Color]
  # @param error_bg_color [Color]
  # @param error_active_bg_color [Color]
  # @param scrollbar_color [Color]
  # @param custom [Hash{Symbol => Color}] app-specific tokens, see {#custom}.
  # @raise [TypeError] when a token is not a {Color}, or `custom` is not a
  #   `Hash{Symbol => Color}`.
  def initialize(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
                 error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: {})
    { active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
      error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color: }.each do |name, value|
      raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)

    custom.each do |key, value|
      raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
      raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    super(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
          error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: custom.dup.freeze)
  end

  # Looks up an app-specific token from {#custom}.
  # @param token [Symbol]
  # @return [Color]
  # @raise [KeyError] when the token is not present — a typo should fail
  #   loudly, not paint in a default.
  def [](token) = custom.fetch(token)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#handle_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # Renders `text` in the foreground color of the app-specific `token`
  # — the generic counterpart of {#active_border} for {#custom} tokens, and
  # the route for an app's own status-line chrome:
  #
  #   "q #{screen.theme.fg(:hint, "quit")}"   # => "q \e[38;5;245mquit\e[0m"
  #
  # The color is baked into the returned String, so text built this way does
  # *not* restyle on a {Screen#theme=} — rebuild it from
  # {Component#handle_theme_changed} instead.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def fg(token, text) = wrap(text, self[token], :fg)

  # Renders `text` on the background color of the app-specific `token`
  # — the generic counterpart of {#active_bg} for {#custom} tokens.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def bg(token, text) = wrap(text, self[token], :bg)

  # Renders `text` on the {#active_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_bg(text) = wrap(text, active_bg_color, :bg)

  # Renders `text` in the {#active_border_color} foreground. Content
  # passes through verbatim, so it may embed non-SGR escapes (cursor
  # moves in a border string).
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_border(text) = wrap(text, active_border_color, :fg)

  # Renders `text` on the {#input_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def input_bg(text) = wrap(text, input_bg_color, :bg)

  # The colors Tuile used before themes existed, tuned for dark terminal
  # backgrounds. GREY37 (palette 59) is what Rainbow emits for
  # `:darkslategray`; GREY27
  # (238, ~#444444) sits in the grayscale ramp, bright enough to stand
  # out against non-pure-black dark terminal themes (Gruvbox/Solarized/
  # OneDark base backgrounds sit in the #1d–#2d range) yet distinctly
  # darker than the active highlight at 59 (~#5f5f5f). The scrollbar reuses
  # GREY37, giving the handle the weight of the selection well and leaving
  # the sparser track glyph near-invisible.
  #
  # `error_color` is INDIAN_RED1 (203, ~#ff5f5f) rather than a pure RED1
  # (196): the message sits beside a field on the terminal's own background,
  # and the softer red keeps its contrast there while pure red vibrates.
  #
  # The error wells are palette 88 (~#870000) and LIGHT_PINK4 (95, ~#875f5f)
  # — split on lightness the way GREY27/GREY37 are, so the focused one is the
  # *lighter* well and the pair reads as a well rather than an alarm block.
  # Both survive `palette256` as themselves and stay distinct from each other
  # there, which is what keeps focus visible on an invalid field. The focused
  # well stays out of the bright mid-reds around #af5f5f: that is where
  # terminals put the cursor, and a caret sitting in an invalid field blurs
  # into a well of its own color.
  #
  # `placeholder_color` is GREY66 (248, ~#a8a8a8): dimmer than the terminal's
  # own foreground, so an empty field's hint reads as absent-value rather than
  # as typed text. It is the *dimmest* grey that still quantizes to `:white` on
  # a 16-color terminal — everything below 248 lands on `:bright_black`
  # alongside both wells, where the hint is not subtle but gone
  # (`design/decisions.md` `D_placeholder`).
  # @return [Theme]
  DARK = new(active_bg_color: Color::GREY37,
             active_border_color: Color::GREEN,
             input_bg_color: Color::GREY27,
             placeholder_color: Color::GREY66,
             error_color: Color::INDIAN_RED1,
             error_bg_color: Color.palette(88),
             error_active_bg_color: Color::LIGHT_PINK4,
             scrollbar_color: Color::GREY37)

  # Counterparts legible on light terminal backgrounds: grayscale-ramp
  # highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253
  # ~#dadada — dark enough to read as a "well" against white, one step
  # lighter than the active highlight). `active_border_color` stays the
  # named green — named ANSI colors are remapped by the terminal's own
  # palette, so the theme picks a light-appropriate green for us. GREY62
  # (247, ~#9e9e9e) is the scrollbar: a *foreground* against pale, so it
  # goes a step darker than the highlights rather than matching them. RED3
  # (124, ~#af0000) is the error ink, dark for the same reason — the light
  # red {DARK} uses would wash out on white.
  #
  # The error wells are MISTY_ROSE1 (224, ~#ffd7d7) and LIGHT_PINK1 (217,
  # ~#ffafaf) — near-white tints that read as a well by *hue* rather than by
  # weight, and darken on focus as the grey pair does. 224 is the palest red
  # the 256-color palette holds: anything subtler quantizes onto the grey ramp
  # (`Color.hex("#ffeaea")` → 255) and the signal is gone entirely on a
  # 256-color terminal. It sits a shade *above* GREY85 rather than below it,
  # so an invalid field reads level with a valid one rather than more
  # recessed — the price of staying close to a white background.
  #
  # `placeholder_color` mirrors {DARK}'s rule from the other side: GREY62 (247,
  # ~#9e9e9e) is the *palest* grey that still quantizes to `:bright_black` on a
  # 16-color terminal, where both light wells are `:white`. It doubles as the
  # scrollbar ink, which wants the same thing — a foreground that recedes
  # against pale without vanishing into it.
  # @return [Theme]
  LIGHT = new(active_bg_color: Color::GREY82,
              active_border_color: Color::GREEN,
              input_bg_color: Color::GREY85,
              placeholder_color: Color::GREY62,
              error_color: Color::RED3,
              error_bg_color: Color::MISTY_ROSE1,
              error_active_bg_color: Color::LIGHT_PINK1,
              scrollbar_color: Color::GREY62)

  private

  # The single sanctioned place for verbatim SGR wrapping: `text` is not
  # parsed or validated, so callers may embed non-SGR escapes. Emits the
  # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
  # text.
  # @param text [String]
  # @param color [Color]
  # @param target [Symbol] `:fg` or `:bg`.
  # @return [String]
  def wrap(text, color, target)
    "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
  end
end

#active_border_color ⇒ Color (readonly)

Foreground of a Component::Window border when the window is on the active (focus) chain.

Returns:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/tuile/theme.rb', line 100

class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color,
                          :placeholder_color, :error_color, :error_bg_color, :error_active_bg_color,
                          :scrollbar_color, :custom)
  # @param active_bg_color [Color]
  # @param active_border_color [Color]
  # @param input_bg_color [Color]
  # @param placeholder_color [Color]
  # @param error_color [Color]
  # @param error_bg_color [Color]
  # @param error_active_bg_color [Color]
  # @param scrollbar_color [Color]
  # @param custom [Hash{Symbol => Color}] app-specific tokens, see {#custom}.
  # @raise [TypeError] when a token is not a {Color}, or `custom` is not a
  #   `Hash{Symbol => Color}`.
  def initialize(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
                 error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: {})
    { active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
      error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color: }.each do |name, value|
      raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)

    custom.each do |key, value|
      raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
      raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    super(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
          error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: custom.dup.freeze)
  end

  # Looks up an app-specific token from {#custom}.
  # @param token [Symbol]
  # @return [Color]
  # @raise [KeyError] when the token is not present — a typo should fail
  #   loudly, not paint in a default.
  def [](token) = custom.fetch(token)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#handle_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # Renders `text` in the foreground color of the app-specific `token`
  # — the generic counterpart of {#active_border} for {#custom} tokens, and
  # the route for an app's own status-line chrome:
  #
  #   "q #{screen.theme.fg(:hint, "quit")}"   # => "q \e[38;5;245mquit\e[0m"
  #
  # The color is baked into the returned String, so text built this way does
  # *not* restyle on a {Screen#theme=} — rebuild it from
  # {Component#handle_theme_changed} instead.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def fg(token, text) = wrap(text, self[token], :fg)

  # Renders `text` on the background color of the app-specific `token`
  # — the generic counterpart of {#active_bg} for {#custom} tokens.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def bg(token, text) = wrap(text, self[token], :bg)

  # Renders `text` on the {#active_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_bg(text) = wrap(text, active_bg_color, :bg)

  # Renders `text` in the {#active_border_color} foreground. Content
  # passes through verbatim, so it may embed non-SGR escapes (cursor
  # moves in a border string).
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_border(text) = wrap(text, active_border_color, :fg)

  # Renders `text` on the {#input_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def input_bg(text) = wrap(text, input_bg_color, :bg)

  # The colors Tuile used before themes existed, tuned for dark terminal
  # backgrounds. GREY37 (palette 59) is what Rainbow emits for
  # `:darkslategray`; GREY27
  # (238, ~#444444) sits in the grayscale ramp, bright enough to stand
  # out against non-pure-black dark terminal themes (Gruvbox/Solarized/
  # OneDark base backgrounds sit in the #1d–#2d range) yet distinctly
  # darker than the active highlight at 59 (~#5f5f5f). The scrollbar reuses
  # GREY37, giving the handle the weight of the selection well and leaving
  # the sparser track glyph near-invisible.
  #
  # `error_color` is INDIAN_RED1 (203, ~#ff5f5f) rather than a pure RED1
  # (196): the message sits beside a field on the terminal's own background,
  # and the softer red keeps its contrast there while pure red vibrates.
  #
  # The error wells are palette 88 (~#870000) and LIGHT_PINK4 (95, ~#875f5f)
  # — split on lightness the way GREY27/GREY37 are, so the focused one is the
  # *lighter* well and the pair reads as a well rather than an alarm block.
  # Both survive `palette256` as themselves and stay distinct from each other
  # there, which is what keeps focus visible on an invalid field. The focused
  # well stays out of the bright mid-reds around #af5f5f: that is where
  # terminals put the cursor, and a caret sitting in an invalid field blurs
  # into a well of its own color.
  #
  # `placeholder_color` is GREY66 (248, ~#a8a8a8): dimmer than the terminal's
  # own foreground, so an empty field's hint reads as absent-value rather than
  # as typed text. It is the *dimmest* grey that still quantizes to `:white` on
  # a 16-color terminal — everything below 248 lands on `:bright_black`
  # alongside both wells, where the hint is not subtle but gone
  # (`design/decisions.md` `D_placeholder`).
  # @return [Theme]
  DARK = new(active_bg_color: Color::GREY37,
             active_border_color: Color::GREEN,
             input_bg_color: Color::GREY27,
             placeholder_color: Color::GREY66,
             error_color: Color::INDIAN_RED1,
             error_bg_color: Color.palette(88),
             error_active_bg_color: Color::LIGHT_PINK4,
             scrollbar_color: Color::GREY37)

  # Counterparts legible on light terminal backgrounds: grayscale-ramp
  # highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253
  # ~#dadada — dark enough to read as a "well" against white, one step
  # lighter than the active highlight). `active_border_color` stays the
  # named green — named ANSI colors are remapped by the terminal's own
  # palette, so the theme picks a light-appropriate green for us. GREY62
  # (247, ~#9e9e9e) is the scrollbar: a *foreground* against pale, so it
  # goes a step darker than the highlights rather than matching them. RED3
  # (124, ~#af0000) is the error ink, dark for the same reason — the light
  # red {DARK} uses would wash out on white.
  #
  # The error wells are MISTY_ROSE1 (224, ~#ffd7d7) and LIGHT_PINK1 (217,
  # ~#ffafaf) — near-white tints that read as a well by *hue* rather than by
  # weight, and darken on focus as the grey pair does. 224 is the palest red
  # the 256-color palette holds: anything subtler quantizes onto the grey ramp
  # (`Color.hex("#ffeaea")` → 255) and the signal is gone entirely on a
  # 256-color terminal. It sits a shade *above* GREY85 rather than below it,
  # so an invalid field reads level with a valid one rather than more
  # recessed — the price of staying close to a white background.
  #
  # `placeholder_color` mirrors {DARK}'s rule from the other side: GREY62 (247,
  # ~#9e9e9e) is the *palest* grey that still quantizes to `:bright_black` on a
  # 16-color terminal, where both light wells are `:white`. It doubles as the
  # scrollbar ink, which wants the same thing — a foreground that recedes
  # against pale without vanishing into it.
  # @return [Theme]
  LIGHT = new(active_bg_color: Color::GREY82,
              active_border_color: Color::GREEN,
              input_bg_color: Color::GREY85,
              placeholder_color: Color::GREY62,
              error_color: Color::RED3,
              error_bg_color: Color::MISTY_ROSE1,
              error_active_bg_color: Color::LIGHT_PINK1,
              scrollbar_color: Color::GREY62)

  private

  # The single sanctioned place for verbatim SGR wrapping: `text` is not
  # parsed or validated, so callers may embed non-SGR escapes. Emits the
  # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
  # text.
  # @param text [String]
  # @param color [Color]
  # @param target [Symbol] `:fg` or `:bg`.
  # @return [String]
  def wrap(text, color, target)
    "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
  end
end

#custom ⇒ ::Hash[Symbol, Color] (readonly)

App-specific color tokens; empty in the built-in themes. Frozen — build a changed theme via with(custom: ...). Prefer #[] for lookups (it fail-fasts on typos); read this directly to enumerate the tokens.

Returns:

  • (::Hash[Symbol, Color]) 


100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/tuile/theme.rb', line 100

class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color,
                          :placeholder_color, :error_color, :error_bg_color, :error_active_bg_color,
                          :scrollbar_color, :custom)
  # @param active_bg_color [Color]
  # @param active_border_color [Color]
  # @param input_bg_color [Color]
  # @param placeholder_color [Color]
  # @param error_color [Color]
  # @param error_bg_color [Color]
  # @param error_active_bg_color [Color]
  # @param scrollbar_color [Color]
  # @param custom [Hash{Symbol => Color}] app-specific tokens, see {#custom}.
  # @raise [TypeError] when a token is not a {Color}, or `custom` is not a
  #   `Hash{Symbol => Color}`.
  def initialize(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
                 error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: {})
    { active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
      error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color: }.each do |name, value|
      raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)

    custom.each do |key, value|
      raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
      raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    super(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
          error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: custom.dup.freeze)
  end

  # Looks up an app-specific token from {#custom}.
  # @param token [Symbol]
  # @return [Color]
  # @raise [KeyError] when the token is not present — a typo should fail
  #   loudly, not paint in a default.
  def [](token) = custom.fetch(token)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#handle_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # Renders `text` in the foreground color of the app-specific `token`
  # — the generic counterpart of {#active_border} for {#custom} tokens, and
  # the route for an app's own status-line chrome:
  #
  #   "q #{screen.theme.fg(:hint, "quit")}"   # => "q \e[38;5;245mquit\e[0m"
  #
  # The color is baked into the returned String, so text built this way does
  # *not* restyle on a {Screen#theme=} — rebuild it from
  # {Component#handle_theme_changed} instead.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def fg(token, text) = wrap(text, self[token], :fg)

  # Renders `text` on the background color of the app-specific `token`
  # — the generic counterpart of {#active_bg} for {#custom} tokens.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def bg(token, text) = wrap(text, self[token], :bg)

  # Renders `text` on the {#active_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_bg(text) = wrap(text, active_bg_color, :bg)

  # Renders `text` in the {#active_border_color} foreground. Content
  # passes through verbatim, so it may embed non-SGR escapes (cursor
  # moves in a border string).
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_border(text) = wrap(text, active_border_color, :fg)

  # Renders `text` on the {#input_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def input_bg(text) = wrap(text, input_bg_color, :bg)

  # The colors Tuile used before themes existed, tuned for dark terminal
  # backgrounds. GREY37 (palette 59) is what Rainbow emits for
  # `:darkslategray`; GREY27
  # (238, ~#444444) sits in the grayscale ramp, bright enough to stand
  # out against non-pure-black dark terminal themes (Gruvbox/Solarized/
  # OneDark base backgrounds sit in the #1d–#2d range) yet distinctly
  # darker than the active highlight at 59 (~#5f5f5f). The scrollbar reuses
  # GREY37, giving the handle the weight of the selection well and leaving
  # the sparser track glyph near-invisible.
  #
  # `error_color` is INDIAN_RED1 (203, ~#ff5f5f) rather than a pure RED1
  # (196): the message sits beside a field on the terminal's own background,
  # and the softer red keeps its contrast there while pure red vibrates.
  #
  # The error wells are palette 88 (~#870000) and LIGHT_PINK4 (95, ~#875f5f)
  # — split on lightness the way GREY27/GREY37 are, so the focused one is the
  # *lighter* well and the pair reads as a well rather than an alarm block.
  # Both survive `palette256` as themselves and stay distinct from each other
  # there, which is what keeps focus visible on an invalid field. The focused
  # well stays out of the bright mid-reds around #af5f5f: that is where
  # terminals put the cursor, and a caret sitting in an invalid field blurs
  # into a well of its own color.
  #
  # `placeholder_color` is GREY66 (248, ~#a8a8a8): dimmer than the terminal's
  # own foreground, so an empty field's hint reads as absent-value rather than
  # as typed text. It is the *dimmest* grey that still quantizes to `:white` on
  # a 16-color terminal — everything below 248 lands on `:bright_black`
  # alongside both wells, where the hint is not subtle but gone
  # (`design/decisions.md` `D_placeholder`).
  # @return [Theme]
  DARK = new(active_bg_color: Color::GREY37,
             active_border_color: Color::GREEN,
             input_bg_color: Color::GREY27,
             placeholder_color: Color::GREY66,
             error_color: Color::INDIAN_RED1,
             error_bg_color: Color.palette(88),
             error_active_bg_color: Color::LIGHT_PINK4,
             scrollbar_color: Color::GREY37)

  # Counterparts legible on light terminal backgrounds: grayscale-ramp
  # highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253
  # ~#dadada — dark enough to read as a "well" against white, one step
  # lighter than the active highlight). `active_border_color` stays the
  # named green — named ANSI colors are remapped by the terminal's own
  # palette, so the theme picks a light-appropriate green for us. GREY62
  # (247, ~#9e9e9e) is the scrollbar: a *foreground* against pale, so it
  # goes a step darker than the highlights rather than matching them. RED3
  # (124, ~#af0000) is the error ink, dark for the same reason — the light
  # red {DARK} uses would wash out on white.
  #
  # The error wells are MISTY_ROSE1 (224, ~#ffd7d7) and LIGHT_PINK1 (217,
  # ~#ffafaf) — near-white tints that read as a well by *hue* rather than by
  # weight, and darken on focus as the grey pair does. 224 is the palest red
  # the 256-color palette holds: anything subtler quantizes onto the grey ramp
  # (`Color.hex("#ffeaea")` → 255) and the signal is gone entirely on a
  # 256-color terminal. It sits a shade *above* GREY85 rather than below it,
  # so an invalid field reads level with a valid one rather than more
  # recessed — the price of staying close to a white background.
  #
  # `placeholder_color` mirrors {DARK}'s rule from the other side: GREY62 (247,
  # ~#9e9e9e) is the *palest* grey that still quantizes to `:bright_black` on a
  # 16-color terminal, where both light wells are `:white`. It doubles as the
  # scrollbar ink, which wants the same thing — a foreground that recedes
  # against pale without vanishing into it.
  # @return [Theme]
  LIGHT = new(active_bg_color: Color::GREY82,
              active_border_color: Color::GREEN,
              input_bg_color: Color::GREY85,
              placeholder_color: Color::GREY62,
              error_color: Color::RED3,
              error_bg_color: Color::MISTY_ROSE1,
              error_active_bg_color: Color::LIGHT_PINK1,
              scrollbar_color: Color::GREY62)

  private

  # The single sanctioned place for verbatim SGR wrapping: `text` is not
  # parsed or validated, so callers may embed non-SGR escapes. Emits the
  # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
  # text.
  # @param text [String]
  # @param color [Color]
  # @param target [Symbol] `:fg` or `:bg`.
  # @return [String]
  def wrap(text, color, target)
    "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
  end
end

#error_active_bg_color ⇒ Color (readonly)

Well of an invalid field that also has focus — #active_bg_color's red counterpart. Must stay distinguishable from #error_bg_color after Color#quantize, or a focused invalid Component::Select (which paints no caret) shows no focus at all.

Returns:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/tuile/theme.rb', line 100

class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color,
                          :placeholder_color, :error_color, :error_bg_color, :error_active_bg_color,
                          :scrollbar_color, :custom)
  # @param active_bg_color [Color]
  # @param active_border_color [Color]
  # @param input_bg_color [Color]
  # @param placeholder_color [Color]
  # @param error_color [Color]
  # @param error_bg_color [Color]
  # @param error_active_bg_color [Color]
  # @param scrollbar_color [Color]
  # @param custom [Hash{Symbol => Color}] app-specific tokens, see {#custom}.
  # @raise [TypeError] when a token is not a {Color}, or `custom` is not a
  #   `Hash{Symbol => Color}`.
  def initialize(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
                 error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: {})
    { active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
      error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color: }.each do |name, value|
      raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)

    custom.each do |key, value|
      raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
      raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    super(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
          error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: custom.dup.freeze)
  end

  # Looks up an app-specific token from {#custom}.
  # @param token [Symbol]
  # @return [Color]
  # @raise [KeyError] when the token is not present — a typo should fail
  #   loudly, not paint in a default.
  def [](token) = custom.fetch(token)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#handle_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # Renders `text` in the foreground color of the app-specific `token`
  # — the generic counterpart of {#active_border} for {#custom} tokens, and
  # the route for an app's own status-line chrome:
  #
  #   "q #{screen.theme.fg(:hint, "quit")}"   # => "q \e[38;5;245mquit\e[0m"
  #
  # The color is baked into the returned String, so text built this way does
  # *not* restyle on a {Screen#theme=} — rebuild it from
  # {Component#handle_theme_changed} instead.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def fg(token, text) = wrap(text, self[token], :fg)

  # Renders `text` on the background color of the app-specific `token`
  # — the generic counterpart of {#active_bg} for {#custom} tokens.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def bg(token, text) = wrap(text, self[token], :bg)

  # Renders `text` on the {#active_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_bg(text) = wrap(text, active_bg_color, :bg)

  # Renders `text` in the {#active_border_color} foreground. Content
  # passes through verbatim, so it may embed non-SGR escapes (cursor
  # moves in a border string).
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_border(text) = wrap(text, active_border_color, :fg)

  # Renders `text` on the {#input_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def input_bg(text) = wrap(text, input_bg_color, :bg)

  # The colors Tuile used before themes existed, tuned for dark terminal
  # backgrounds. GREY37 (palette 59) is what Rainbow emits for
  # `:darkslategray`; GREY27
  # (238, ~#444444) sits in the grayscale ramp, bright enough to stand
  # out against non-pure-black dark terminal themes (Gruvbox/Solarized/
  # OneDark base backgrounds sit in the #1d–#2d range) yet distinctly
  # darker than the active highlight at 59 (~#5f5f5f). The scrollbar reuses
  # GREY37, giving the handle the weight of the selection well and leaving
  # the sparser track glyph near-invisible.
  #
  # `error_color` is INDIAN_RED1 (203, ~#ff5f5f) rather than a pure RED1
  # (196): the message sits beside a field on the terminal's own background,
  # and the softer red keeps its contrast there while pure red vibrates.
  #
  # The error wells are palette 88 (~#870000) and LIGHT_PINK4 (95, ~#875f5f)
  # — split on lightness the way GREY27/GREY37 are, so the focused one is the
  # *lighter* well and the pair reads as a well rather than an alarm block.
  # Both survive `palette256` as themselves and stay distinct from each other
  # there, which is what keeps focus visible on an invalid field. The focused
  # well stays out of the bright mid-reds around #af5f5f: that is where
  # terminals put the cursor, and a caret sitting in an invalid field blurs
  # into a well of its own color.
  #
  # `placeholder_color` is GREY66 (248, ~#a8a8a8): dimmer than the terminal's
  # own foreground, so an empty field's hint reads as absent-value rather than
  # as typed text. It is the *dimmest* grey that still quantizes to `:white` on
  # a 16-color terminal — everything below 248 lands on `:bright_black`
  # alongside both wells, where the hint is not subtle but gone
  # (`design/decisions.md` `D_placeholder`).
  # @return [Theme]
  DARK = new(active_bg_color: Color::GREY37,
             active_border_color: Color::GREEN,
             input_bg_color: Color::GREY27,
             placeholder_color: Color::GREY66,
             error_color: Color::INDIAN_RED1,
             error_bg_color: Color.palette(88),
             error_active_bg_color: Color::LIGHT_PINK4,
             scrollbar_color: Color::GREY37)

  # Counterparts legible on light terminal backgrounds: grayscale-ramp
  # highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253
  # ~#dadada — dark enough to read as a "well" against white, one step
  # lighter than the active highlight). `active_border_color` stays the
  # named green — named ANSI colors are remapped by the terminal's own
  # palette, so the theme picks a light-appropriate green for us. GREY62
  # (247, ~#9e9e9e) is the scrollbar: a *foreground* against pale, so it
  # goes a step darker than the highlights rather than matching them. RED3
  # (124, ~#af0000) is the error ink, dark for the same reason — the light
  # red {DARK} uses would wash out on white.
  #
  # The error wells are MISTY_ROSE1 (224, ~#ffd7d7) and LIGHT_PINK1 (217,
  # ~#ffafaf) — near-white tints that read as a well by *hue* rather than by
  # weight, and darken on focus as the grey pair does. 224 is the palest red
  # the 256-color palette holds: anything subtler quantizes onto the grey ramp
  # (`Color.hex("#ffeaea")` → 255) and the signal is gone entirely on a
  # 256-color terminal. It sits a shade *above* GREY85 rather than below it,
  # so an invalid field reads level with a valid one rather than more
  # recessed — the price of staying close to a white background.
  #
  # `placeholder_color` mirrors {DARK}'s rule from the other side: GREY62 (247,
  # ~#9e9e9e) is the *palest* grey that still quantizes to `:bright_black` on a
  # 16-color terminal, where both light wells are `:white`. It doubles as the
  # scrollbar ink, which wants the same thing — a foreground that recedes
  # against pale without vanishing into it.
  # @return [Theme]
  LIGHT = new(active_bg_color: Color::GREY82,
              active_border_color: Color::GREEN,
              input_bg_color: Color::GREY85,
              placeholder_color: Color::GREY62,
              error_color: Color::RED3,
              error_bg_color: Color::MISTY_ROSE1,
              error_active_bg_color: Color::LIGHT_PINK1,
              scrollbar_color: Color::GREY62)

  private

  # The single sanctioned place for verbatim SGR wrapping: `text` is not
  # parsed or validated, so callers may embed non-SGR escapes. Emits the
  # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
  # text.
  # @param text [String]
  # @param color [Color]
  # @param target [Symbol] `:fg` or `:bg`.
  # @return [String]
  def wrap(text, color, target)
    "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
  end
end

#error_bg_color ⇒ Color (readonly)

Resting well of a field that is invalid — #input_bg_color's red counterpart, and the reason the pair exists rather than one flat error color: a field's well is what shows its boundary, so an invalid field needs a well and still needs to show focus.

Returns:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/tuile/theme.rb', line 100

class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color,
                          :placeholder_color, :error_color, :error_bg_color, :error_active_bg_color,
                          :scrollbar_color, :custom)
  # @param active_bg_color [Color]
  # @param active_border_color [Color]
  # @param input_bg_color [Color]
  # @param placeholder_color [Color]
  # @param error_color [Color]
  # @param error_bg_color [Color]
  # @param error_active_bg_color [Color]
  # @param scrollbar_color [Color]
  # @param custom [Hash{Symbol => Color}] app-specific tokens, see {#custom}.
  # @raise [TypeError] when a token is not a {Color}, or `custom` is not a
  #   `Hash{Symbol => Color}`.
  def initialize(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
                 error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: {})
    { active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
      error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color: }.each do |name, value|
      raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)

    custom.each do |key, value|
      raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
      raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    super(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
          error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: custom.dup.freeze)
  end

  # Looks up an app-specific token from {#custom}.
  # @param token [Symbol]
  # @return [Color]
  # @raise [KeyError] when the token is not present — a typo should fail
  #   loudly, not paint in a default.
  def [](token) = custom.fetch(token)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#handle_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # Renders `text` in the foreground color of the app-specific `token`
  # — the generic counterpart of {#active_border} for {#custom} tokens, and
  # the route for an app's own status-line chrome:
  #
  #   "q #{screen.theme.fg(:hint, "quit")}"   # => "q \e[38;5;245mquit\e[0m"
  #
  # The color is baked into the returned String, so text built this way does
  # *not* restyle on a {Screen#theme=} — rebuild it from
  # {Component#handle_theme_changed} instead.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def fg(token, text) = wrap(text, self[token], :fg)

  # Renders `text` on the background color of the app-specific `token`
  # — the generic counterpart of {#active_bg} for {#custom} tokens.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def bg(token, text) = wrap(text, self[token], :bg)

  # Renders `text` on the {#active_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_bg(text) = wrap(text, active_bg_color, :bg)

  # Renders `text` in the {#active_border_color} foreground. Content
  # passes through verbatim, so it may embed non-SGR escapes (cursor
  # moves in a border string).
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_border(text) = wrap(text, active_border_color, :fg)

  # Renders `text` on the {#input_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def input_bg(text) = wrap(text, input_bg_color, :bg)

  # The colors Tuile used before themes existed, tuned for dark terminal
  # backgrounds. GREY37 (palette 59) is what Rainbow emits for
  # `:darkslategray`; GREY27
  # (238, ~#444444) sits in the grayscale ramp, bright enough to stand
  # out against non-pure-black dark terminal themes (Gruvbox/Solarized/
  # OneDark base backgrounds sit in the #1d–#2d range) yet distinctly
  # darker than the active highlight at 59 (~#5f5f5f). The scrollbar reuses
  # GREY37, giving the handle the weight of the selection well and leaving
  # the sparser track glyph near-invisible.
  #
  # `error_color` is INDIAN_RED1 (203, ~#ff5f5f) rather than a pure RED1
  # (196): the message sits beside a field on the terminal's own background,
  # and the softer red keeps its contrast there while pure red vibrates.
  #
  # The error wells are palette 88 (~#870000) and LIGHT_PINK4 (95, ~#875f5f)
  # — split on lightness the way GREY27/GREY37 are, so the focused one is the
  # *lighter* well and the pair reads as a well rather than an alarm block.
  # Both survive `palette256` as themselves and stay distinct from each other
  # there, which is what keeps focus visible on an invalid field. The focused
  # well stays out of the bright mid-reds around #af5f5f: that is where
  # terminals put the cursor, and a caret sitting in an invalid field blurs
  # into a well of its own color.
  #
  # `placeholder_color` is GREY66 (248, ~#a8a8a8): dimmer than the terminal's
  # own foreground, so an empty field's hint reads as absent-value rather than
  # as typed text. It is the *dimmest* grey that still quantizes to `:white` on
  # a 16-color terminal — everything below 248 lands on `:bright_black`
  # alongside both wells, where the hint is not subtle but gone
  # (`design/decisions.md` `D_placeholder`).
  # @return [Theme]
  DARK = new(active_bg_color: Color::GREY37,
             active_border_color: Color::GREEN,
             input_bg_color: Color::GREY27,
             placeholder_color: Color::GREY66,
             error_color: Color::INDIAN_RED1,
             error_bg_color: Color.palette(88),
             error_active_bg_color: Color::LIGHT_PINK4,
             scrollbar_color: Color::GREY37)

  # Counterparts legible on light terminal backgrounds: grayscale-ramp
  # highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253
  # ~#dadada — dark enough to read as a "well" against white, one step
  # lighter than the active highlight). `active_border_color` stays the
  # named green — named ANSI colors are remapped by the terminal's own
  # palette, so the theme picks a light-appropriate green for us. GREY62
  # (247, ~#9e9e9e) is the scrollbar: a *foreground* against pale, so it
  # goes a step darker than the highlights rather than matching them. RED3
  # (124, ~#af0000) is the error ink, dark for the same reason — the light
  # red {DARK} uses would wash out on white.
  #
  # The error wells are MISTY_ROSE1 (224, ~#ffd7d7) and LIGHT_PINK1 (217,
  # ~#ffafaf) — near-white tints that read as a well by *hue* rather than by
  # weight, and darken on focus as the grey pair does. 224 is the palest red
  # the 256-color palette holds: anything subtler quantizes onto the grey ramp
  # (`Color.hex("#ffeaea")` → 255) and the signal is gone entirely on a
  # 256-color terminal. It sits a shade *above* GREY85 rather than below it,
  # so an invalid field reads level with a valid one rather than more
  # recessed — the price of staying close to a white background.
  #
  # `placeholder_color` mirrors {DARK}'s rule from the other side: GREY62 (247,
  # ~#9e9e9e) is the *palest* grey that still quantizes to `:bright_black` on a
  # 16-color terminal, where both light wells are `:white`. It doubles as the
  # scrollbar ink, which wants the same thing — a foreground that recedes
  # against pale without vanishing into it.
  # @return [Theme]
  LIGHT = new(active_bg_color: Color::GREY82,
              active_border_color: Color::GREEN,
              input_bg_color: Color::GREY85,
              placeholder_color: Color::GREY62,
              error_color: Color::RED3,
              error_bg_color: Color::MISTY_ROSE1,
              error_active_bg_color: Color::LIGHT_PINK1,
              scrollbar_color: Color::GREY62)

  private

  # The single sanctioned place for verbatim SGR wrapping: `text` is not
  # parsed or validated, so callers may embed non-SGR escapes. Emits the
  # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
  # text.
  # @param text [String]
  # @param color [Color]
  # @param target [Symbol] `:fg` or `:bg`.
  # @return [String]
  def wrap(text, color, target)
    "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
  end
end

#error_color ⇒ Color (readonly)

Foreground for the message beside an invalid field — the text a container paints from Component::HasValidation#error_message. The field's own face uses #error_bg_color instead.

Returns:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/tuile/theme.rb', line 100

class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color,
                          :placeholder_color, :error_color, :error_bg_color, :error_active_bg_color,
                          :scrollbar_color, :custom)
  # @param active_bg_color [Color]
  # @param active_border_color [Color]
  # @param input_bg_color [Color]
  # @param placeholder_color [Color]
  # @param error_color [Color]
  # @param error_bg_color [Color]
  # @param error_active_bg_color [Color]
  # @param scrollbar_color [Color]
  # @param custom [Hash{Symbol => Color}] app-specific tokens, see {#custom}.
  # @raise [TypeError] when a token is not a {Color}, or `custom` is not a
  #   `Hash{Symbol => Color}`.
  def initialize(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
                 error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: {})
    { active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
      error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color: }.each do |name, value|
      raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)

    custom.each do |key, value|
      raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
      raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    super(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
          error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: custom.dup.freeze)
  end

  # Looks up an app-specific token from {#custom}.
  # @param token [Symbol]
  # @return [Color]
  # @raise [KeyError] when the token is not present — a typo should fail
  #   loudly, not paint in a default.
  def [](token) = custom.fetch(token)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#handle_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # Renders `text` in the foreground color of the app-specific `token`
  # — the generic counterpart of {#active_border} for {#custom} tokens, and
  # the route for an app's own status-line chrome:
  #
  #   "q #{screen.theme.fg(:hint, "quit")}"   # => "q \e[38;5;245mquit\e[0m"
  #
  # The color is baked into the returned String, so text built this way does
  # *not* restyle on a {Screen#theme=} — rebuild it from
  # {Component#handle_theme_changed} instead.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def fg(token, text) = wrap(text, self[token], :fg)

  # Renders `text` on the background color of the app-specific `token`
  # — the generic counterpart of {#active_bg} for {#custom} tokens.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def bg(token, text) = wrap(text, self[token], :bg)

  # Renders `text` on the {#active_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_bg(text) = wrap(text, active_bg_color, :bg)

  # Renders `text` in the {#active_border_color} foreground. Content
  # passes through verbatim, so it may embed non-SGR escapes (cursor
  # moves in a border string).
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_border(text) = wrap(text, active_border_color, :fg)

  # Renders `text` on the {#input_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def input_bg(text) = wrap(text, input_bg_color, :bg)

  # The colors Tuile used before themes existed, tuned for dark terminal
  # backgrounds. GREY37 (palette 59) is what Rainbow emits for
  # `:darkslategray`; GREY27
  # (238, ~#444444) sits in the grayscale ramp, bright enough to stand
  # out against non-pure-black dark terminal themes (Gruvbox/Solarized/
  # OneDark base backgrounds sit in the #1d–#2d range) yet distinctly
  # darker than the active highlight at 59 (~#5f5f5f). The scrollbar reuses
  # GREY37, giving the handle the weight of the selection well and leaving
  # the sparser track glyph near-invisible.
  #
  # `error_color` is INDIAN_RED1 (203, ~#ff5f5f) rather than a pure RED1
  # (196): the message sits beside a field on the terminal's own background,
  # and the softer red keeps its contrast there while pure red vibrates.
  #
  # The error wells are palette 88 (~#870000) and LIGHT_PINK4 (95, ~#875f5f)
  # — split on lightness the way GREY27/GREY37 are, so the focused one is the
  # *lighter* well and the pair reads as a well rather than an alarm block.
  # Both survive `palette256` as themselves and stay distinct from each other
  # there, which is what keeps focus visible on an invalid field. The focused
  # well stays out of the bright mid-reds around #af5f5f: that is where
  # terminals put the cursor, and a caret sitting in an invalid field blurs
  # into a well of its own color.
  #
  # `placeholder_color` is GREY66 (248, ~#a8a8a8): dimmer than the terminal's
  # own foreground, so an empty field's hint reads as absent-value rather than
  # as typed text. It is the *dimmest* grey that still quantizes to `:white` on
  # a 16-color terminal — everything below 248 lands on `:bright_black`
  # alongside both wells, where the hint is not subtle but gone
  # (`design/decisions.md` `D_placeholder`).
  # @return [Theme]
  DARK = new(active_bg_color: Color::GREY37,
             active_border_color: Color::GREEN,
             input_bg_color: Color::GREY27,
             placeholder_color: Color::GREY66,
             error_color: Color::INDIAN_RED1,
             error_bg_color: Color.palette(88),
             error_active_bg_color: Color::LIGHT_PINK4,
             scrollbar_color: Color::GREY37)

  # Counterparts legible on light terminal backgrounds: grayscale-ramp
  # highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253
  # ~#dadada — dark enough to read as a "well" against white, one step
  # lighter than the active highlight). `active_border_color` stays the
  # named green — named ANSI colors are remapped by the terminal's own
  # palette, so the theme picks a light-appropriate green for us. GREY62
  # (247, ~#9e9e9e) is the scrollbar: a *foreground* against pale, so it
  # goes a step darker than the highlights rather than matching them. RED3
  # (124, ~#af0000) is the error ink, dark for the same reason — the light
  # red {DARK} uses would wash out on white.
  #
  # The error wells are MISTY_ROSE1 (224, ~#ffd7d7) and LIGHT_PINK1 (217,
  # ~#ffafaf) — near-white tints that read as a well by *hue* rather than by
  # weight, and darken on focus as the grey pair does. 224 is the palest red
  # the 256-color palette holds: anything subtler quantizes onto the grey ramp
  # (`Color.hex("#ffeaea")` → 255) and the signal is gone entirely on a
  # 256-color terminal. It sits a shade *above* GREY85 rather than below it,
  # so an invalid field reads level with a valid one rather than more
  # recessed — the price of staying close to a white background.
  #
  # `placeholder_color` mirrors {DARK}'s rule from the other side: GREY62 (247,
  # ~#9e9e9e) is the *palest* grey that still quantizes to `:bright_black` on a
  # 16-color terminal, where both light wells are `:white`. It doubles as the
  # scrollbar ink, which wants the same thing — a foreground that recedes
  # against pale without vanishing into it.
  # @return [Theme]
  LIGHT = new(active_bg_color: Color::GREY82,
              active_border_color: Color::GREEN,
              input_bg_color: Color::GREY85,
              placeholder_color: Color::GREY62,
              error_color: Color::RED3,
              error_bg_color: Color::MISTY_ROSE1,
              error_active_bg_color: Color::LIGHT_PINK1,
              scrollbar_color: Color::GREY62)

  private

  # The single sanctioned place for verbatim SGR wrapping: `text` is not
  # parsed or validated, so callers may embed non-SGR escapes. Emits the
  # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
  # text.
  # @param text [String]
  # @param color [Color]
  # @param target [Symbol] `:fg` or `:bg`.
  # @return [String]
  def wrap(text, color, target)
    "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
  end
end

#input_bg_color ⇒ Color (readonly)

Resting background "well" of Component::TextField / Component::TextArea when not active — visibly a field, but distinctly subtler than #active_bg_color.

Returns:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/tuile/theme.rb', line 100

class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color,
                          :placeholder_color, :error_color, :error_bg_color, :error_active_bg_color,
                          :scrollbar_color, :custom)
  # @param active_bg_color [Color]
  # @param active_border_color [Color]
  # @param input_bg_color [Color]
  # @param placeholder_color [Color]
  # @param error_color [Color]
  # @param error_bg_color [Color]
  # @param error_active_bg_color [Color]
  # @param scrollbar_color [Color]
  # @param custom [Hash{Symbol => Color}] app-specific tokens, see {#custom}.
  # @raise [TypeError] when a token is not a {Color}, or `custom` is not a
  #   `Hash{Symbol => Color}`.
  def initialize(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
                 error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: {})
    { active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
      error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color: }.each do |name, value|
      raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)

    custom.each do |key, value|
      raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
      raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    super(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
          error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: custom.dup.freeze)
  end

  # Looks up an app-specific token from {#custom}.
  # @param token [Symbol]
  # @return [Color]
  # @raise [KeyError] when the token is not present — a typo should fail
  #   loudly, not paint in a default.
  def [](token) = custom.fetch(token)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#handle_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # Renders `text` in the foreground color of the app-specific `token`
  # — the generic counterpart of {#active_border} for {#custom} tokens, and
  # the route for an app's own status-line chrome:
  #
  #   "q #{screen.theme.fg(:hint, "quit")}"   # => "q \e[38;5;245mquit\e[0m"
  #
  # The color is baked into the returned String, so text built this way does
  # *not* restyle on a {Screen#theme=} — rebuild it from
  # {Component#handle_theme_changed} instead.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def fg(token, text) = wrap(text, self[token], :fg)

  # Renders `text` on the background color of the app-specific `token`
  # — the generic counterpart of {#active_bg} for {#custom} tokens.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def bg(token, text) = wrap(text, self[token], :bg)

  # Renders `text` on the {#active_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_bg(text) = wrap(text, active_bg_color, :bg)

  # Renders `text` in the {#active_border_color} foreground. Content
  # passes through verbatim, so it may embed non-SGR escapes (cursor
  # moves in a border string).
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_border(text) = wrap(text, active_border_color, :fg)

  # Renders `text` on the {#input_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def input_bg(text) = wrap(text, input_bg_color, :bg)

  # The colors Tuile used before themes existed, tuned for dark terminal
  # backgrounds. GREY37 (palette 59) is what Rainbow emits for
  # `:darkslategray`; GREY27
  # (238, ~#444444) sits in the grayscale ramp, bright enough to stand
  # out against non-pure-black dark terminal themes (Gruvbox/Solarized/
  # OneDark base backgrounds sit in the #1d–#2d range) yet distinctly
  # darker than the active highlight at 59 (~#5f5f5f). The scrollbar reuses
  # GREY37, giving the handle the weight of the selection well and leaving
  # the sparser track glyph near-invisible.
  #
  # `error_color` is INDIAN_RED1 (203, ~#ff5f5f) rather than a pure RED1
  # (196): the message sits beside a field on the terminal's own background,
  # and the softer red keeps its contrast there while pure red vibrates.
  #
  # The error wells are palette 88 (~#870000) and LIGHT_PINK4 (95, ~#875f5f)
  # — split on lightness the way GREY27/GREY37 are, so the focused one is the
  # *lighter* well and the pair reads as a well rather than an alarm block.
  # Both survive `palette256` as themselves and stay distinct from each other
  # there, which is what keeps focus visible on an invalid field. The focused
  # well stays out of the bright mid-reds around #af5f5f: that is where
  # terminals put the cursor, and a caret sitting in an invalid field blurs
  # into a well of its own color.
  #
  # `placeholder_color` is GREY66 (248, ~#a8a8a8): dimmer than the terminal's
  # own foreground, so an empty field's hint reads as absent-value rather than
  # as typed text. It is the *dimmest* grey that still quantizes to `:white` on
  # a 16-color terminal — everything below 248 lands on `:bright_black`
  # alongside both wells, where the hint is not subtle but gone
  # (`design/decisions.md` `D_placeholder`).
  # @return [Theme]
  DARK = new(active_bg_color: Color::GREY37,
             active_border_color: Color::GREEN,
             input_bg_color: Color::GREY27,
             placeholder_color: Color::GREY66,
             error_color: Color::INDIAN_RED1,
             error_bg_color: Color.palette(88),
             error_active_bg_color: Color::LIGHT_PINK4,
             scrollbar_color: Color::GREY37)

  # Counterparts legible on light terminal backgrounds: grayscale-ramp
  # highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253
  # ~#dadada — dark enough to read as a "well" against white, one step
  # lighter than the active highlight). `active_border_color` stays the
  # named green — named ANSI colors are remapped by the terminal's own
  # palette, so the theme picks a light-appropriate green for us. GREY62
  # (247, ~#9e9e9e) is the scrollbar: a *foreground* against pale, so it
  # goes a step darker than the highlights rather than matching them. RED3
  # (124, ~#af0000) is the error ink, dark for the same reason — the light
  # red {DARK} uses would wash out on white.
  #
  # The error wells are MISTY_ROSE1 (224, ~#ffd7d7) and LIGHT_PINK1 (217,
  # ~#ffafaf) — near-white tints that read as a well by *hue* rather than by
  # weight, and darken on focus as the grey pair does. 224 is the palest red
  # the 256-color palette holds: anything subtler quantizes onto the grey ramp
  # (`Color.hex("#ffeaea")` → 255) and the signal is gone entirely on a
  # 256-color terminal. It sits a shade *above* GREY85 rather than below it,
  # so an invalid field reads level with a valid one rather than more
  # recessed — the price of staying close to a white background.
  #
  # `placeholder_color` mirrors {DARK}'s rule from the other side: GREY62 (247,
  # ~#9e9e9e) is the *palest* grey that still quantizes to `:bright_black` on a
  # 16-color terminal, where both light wells are `:white`. It doubles as the
  # scrollbar ink, which wants the same thing — a foreground that recedes
  # against pale without vanishing into it.
  # @return [Theme]
  LIGHT = new(active_bg_color: Color::GREY82,
              active_border_color: Color::GREEN,
              input_bg_color: Color::GREY85,
              placeholder_color: Color::GREY62,
              error_color: Color::RED3,
              error_bg_color: Color::MISTY_ROSE1,
              error_active_bg_color: Color::LIGHT_PINK1,
              scrollbar_color: Color::GREY62)

  private

  # The single sanctioned place for verbatim SGR wrapping: `text` is not
  # parsed or validated, so callers may embed non-SGR escapes. Emits the
  # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
  # text.
  # @param text [String]
  # @param color [Color]
  # @param target [Symbol] `:fg` or `:bg`.
  # @return [String]
  def wrap(text, color, target)
    "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
  end
end

#placeholder_color ⇒ Color (readonly)

Foreground of the hint a field paints into its own empty well (Component::HasPlaceholder) — the one token tuned to be barely visible, since a placeholder the user misses costs nothing.

Returns:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/tuile/theme.rb', line 100

class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color,
                          :placeholder_color, :error_color, :error_bg_color, :error_active_bg_color,
                          :scrollbar_color, :custom)
  # @param active_bg_color [Color]
  # @param active_border_color [Color]
  # @param input_bg_color [Color]
  # @param placeholder_color [Color]
  # @param error_color [Color]
  # @param error_bg_color [Color]
  # @param error_active_bg_color [Color]
  # @param scrollbar_color [Color]
  # @param custom [Hash{Symbol => Color}] app-specific tokens, see {#custom}.
  # @raise [TypeError] when a token is not a {Color}, or `custom` is not a
  #   `Hash{Symbol => Color}`.
  def initialize(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
                 error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: {})
    { active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
      error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color: }.each do |name, value|
      raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)

    custom.each do |key, value|
      raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
      raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    super(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
          error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: custom.dup.freeze)
  end

  # Looks up an app-specific token from {#custom}.
  # @param token [Symbol]
  # @return [Color]
  # @raise [KeyError] when the token is not present — a typo should fail
  #   loudly, not paint in a default.
  def [](token) = custom.fetch(token)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#handle_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # Renders `text` in the foreground color of the app-specific `token`
  # — the generic counterpart of {#active_border} for {#custom} tokens, and
  # the route for an app's own status-line chrome:
  #
  #   "q #{screen.theme.fg(:hint, "quit")}"   # => "q \e[38;5;245mquit\e[0m"
  #
  # The color is baked into the returned String, so text built this way does
  # *not* restyle on a {Screen#theme=} — rebuild it from
  # {Component#handle_theme_changed} instead.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def fg(token, text) = wrap(text, self[token], :fg)

  # Renders `text` on the background color of the app-specific `token`
  # — the generic counterpart of {#active_bg} for {#custom} tokens.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def bg(token, text) = wrap(text, self[token], :bg)

  # Renders `text` on the {#active_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_bg(text) = wrap(text, active_bg_color, :bg)

  # Renders `text` in the {#active_border_color} foreground. Content
  # passes through verbatim, so it may embed non-SGR escapes (cursor
  # moves in a border string).
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_border(text) = wrap(text, active_border_color, :fg)

  # Renders `text` on the {#input_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def input_bg(text) = wrap(text, input_bg_color, :bg)

  # The colors Tuile used before themes existed, tuned for dark terminal
  # backgrounds. GREY37 (palette 59) is what Rainbow emits for
  # `:darkslategray`; GREY27
  # (238, ~#444444) sits in the grayscale ramp, bright enough to stand
  # out against non-pure-black dark terminal themes (Gruvbox/Solarized/
  # OneDark base backgrounds sit in the #1d–#2d range) yet distinctly
  # darker than the active highlight at 59 (~#5f5f5f). The scrollbar reuses
  # GREY37, giving the handle the weight of the selection well and leaving
  # the sparser track glyph near-invisible.
  #
  # `error_color` is INDIAN_RED1 (203, ~#ff5f5f) rather than a pure RED1
  # (196): the message sits beside a field on the terminal's own background,
  # and the softer red keeps its contrast there while pure red vibrates.
  #
  # The error wells are palette 88 (~#870000) and LIGHT_PINK4 (95, ~#875f5f)
  # — split on lightness the way GREY27/GREY37 are, so the focused one is the
  # *lighter* well and the pair reads as a well rather than an alarm block.
  # Both survive `palette256` as themselves and stay distinct from each other
  # there, which is what keeps focus visible on an invalid field. The focused
  # well stays out of the bright mid-reds around #af5f5f: that is where
  # terminals put the cursor, and a caret sitting in an invalid field blurs
  # into a well of its own color.
  #
  # `placeholder_color` is GREY66 (248, ~#a8a8a8): dimmer than the terminal's
  # own foreground, so an empty field's hint reads as absent-value rather than
  # as typed text. It is the *dimmest* grey that still quantizes to `:white` on
  # a 16-color terminal — everything below 248 lands on `:bright_black`
  # alongside both wells, where the hint is not subtle but gone
  # (`design/decisions.md` `D_placeholder`).
  # @return [Theme]
  DARK = new(active_bg_color: Color::GREY37,
             active_border_color: Color::GREEN,
             input_bg_color: Color::GREY27,
             placeholder_color: Color::GREY66,
             error_color: Color::INDIAN_RED1,
             error_bg_color: Color.palette(88),
             error_active_bg_color: Color::LIGHT_PINK4,
             scrollbar_color: Color::GREY37)

  # Counterparts legible on light terminal backgrounds: grayscale-ramp
  # highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253
  # ~#dadada — dark enough to read as a "well" against white, one step
  # lighter than the active highlight). `active_border_color` stays the
  # named green — named ANSI colors are remapped by the terminal's own
  # palette, so the theme picks a light-appropriate green for us. GREY62
  # (247, ~#9e9e9e) is the scrollbar: a *foreground* against pale, so it
  # goes a step darker than the highlights rather than matching them. RED3
  # (124, ~#af0000) is the error ink, dark for the same reason — the light
  # red {DARK} uses would wash out on white.
  #
  # The error wells are MISTY_ROSE1 (224, ~#ffd7d7) and LIGHT_PINK1 (217,
  # ~#ffafaf) — near-white tints that read as a well by *hue* rather than by
  # weight, and darken on focus as the grey pair does. 224 is the palest red
  # the 256-color palette holds: anything subtler quantizes onto the grey ramp
  # (`Color.hex("#ffeaea")` → 255) and the signal is gone entirely on a
  # 256-color terminal. It sits a shade *above* GREY85 rather than below it,
  # so an invalid field reads level with a valid one rather than more
  # recessed — the price of staying close to a white background.
  #
  # `placeholder_color` mirrors {DARK}'s rule from the other side: GREY62 (247,
  # ~#9e9e9e) is the *palest* grey that still quantizes to `:bright_black` on a
  # 16-color terminal, where both light wells are `:white`. It doubles as the
  # scrollbar ink, which wants the same thing — a foreground that recedes
  # against pale without vanishing into it.
  # @return [Theme]
  LIGHT = new(active_bg_color: Color::GREY82,
              active_border_color: Color::GREEN,
              input_bg_color: Color::GREY85,
              placeholder_color: Color::GREY62,
              error_color: Color::RED3,
              error_bg_color: Color::MISTY_ROSE1,
              error_active_bg_color: Color::LIGHT_PINK1,
              scrollbar_color: Color::GREY62)

  private

  # The single sanctioned place for verbatim SGR wrapping: `text` is not
  # parsed or validated, so callers may embed non-SGR escapes. Emits the
  # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
  # text.
  # @param text [String]
  # @param color [Color]
  # @param target [Symbol] `:fg` or `:bg`.
  # @return [String]
  def wrap(text, color, target)
    "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
  end
end

#scrollbar_color ⇒ Color (readonly)

Foreground of the VerticalScrollBar a Component::List or Component::TextView paints down its right edge — handle and track alike, which the glyphs' own ink densities tell apart.

Returns:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/tuile/theme.rb', line 100

class Theme < Data.define(:active_bg_color, :active_border_color, :input_bg_color,
                          :placeholder_color, :error_color, :error_bg_color, :error_active_bg_color,
                          :scrollbar_color, :custom)
  # @param active_bg_color [Color]
  # @param active_border_color [Color]
  # @param input_bg_color [Color]
  # @param placeholder_color [Color]
  # @param error_color [Color]
  # @param error_bg_color [Color]
  # @param error_active_bg_color [Color]
  # @param scrollbar_color [Color]
  # @param custom [Hash{Symbol => Color}] app-specific tokens, see {#custom}.
  # @raise [TypeError] when a token is not a {Color}, or `custom` is not a
  #   `Hash{Symbol => Color}`.
  def initialize(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
                 error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: {})
    { active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
      error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color: }.each do |name, value|
      raise TypeError, "#{name} must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    raise TypeError, "custom must be a Hash, got #{custom.inspect}" unless custom.is_a?(Hash)

    custom.each do |key, value|
      raise TypeError, "custom key must be a Symbol, got #{key.inspect}" unless key.is_a?(Symbol)
      raise TypeError, "custom[#{key.inspect}] must be a Tuile::Color, got #{value.inspect}" unless value.is_a?(Color)
    end
    super(active_bg_color:, active_border_color:, input_bg_color:, placeholder_color:,
          error_color:, error_bg_color:, error_active_bg_color:, scrollbar_color:, custom: custom.dup.freeze)
  end

  # Looks up an app-specific token from {#custom}.
  # @param token [Symbol]
  # @return [Color]
  # @raise [KeyError] when the token is not present — a typo should fail
  #   loudly, not paint in a default.
  def [](token) = custom.fetch(token)

  # The built-in chrome color tokens — every {Data} member bar {#custom}. A
  # {Ref} resolves a name in this set as the chrome color; anything else as a
  # {#custom} token.
  # @return [Array<Symbol>]
  CHROME_TOKENS = (members - %i[custom]).freeze

  # @param name [Symbol] a token name.
  # @return [Boolean] true iff `name` is a built-in chrome token (see
  #   {CHROME_TOKENS}) rather than a {#custom} one.
  def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

  # Builds a {Ref} — a live theme reference for a late-resolved color slot
  # like {Component#bg_color=}. Sugar for `Theme::Ref.new(name)`.
  # @param name [Symbol] a built-in chrome token ({#input_bg_color} etc.) or
  #   a {#custom} token name.
  # @return [Ref]
  def self.ref(name) = Ref.new(name)

  # A live reference to a theme token, resolved against the current theme at
  # paint time rather than baked to a concrete {Color}. Assign one where a
  # slot is resolved late — currently {Component#bg_color=} — and it follows
  # light/dark flips with no {Component#handle_theme_changed} hook:
  #
  #   panel.bg_color = Tuile::Theme.ref(:panel_bg)        # a #custom token
  #   dropdown.bg_color = Tuile::Theme.ref(:input_bg_color) # built-in chrome
  #
  # The name may be a built-in chrome token ({CHROME_TOKENS}) or a {#custom}
  # one; a chrome name takes precedence on the (pathological) collision. This
  # does *not* add a global bg/fg token — it only lets a slot point at a
  # color the theme *already* carries, resolved the same way framework chrome
  # already resolves it.
  #
  # Distinct from {Color.coerce}'s symbol support, which names one of the 16
  # ANSI colors and yields a fixed {Color}; a Ref names a *theme* token and
  # re-reads it each paint.
  #
  # Immutable.
  class Ref < Data.define(:name)
    # Resolves to the concrete {Color} `name` maps to in `theme` — a built-in
    # chrome reader when `name` is one ({Theme.chrome_token?}), else a
    # {#custom} token.
    # @param theme [Theme]
    # @return [Color]
    # @raise [KeyError] when `name` is neither a chrome token nor a {#custom}
    #   token in `theme`.
    def resolve(theme)
      return theme.public_send(name) if Theme.chrome_token?(name)

      theme[name]
    end
  end

  # Renders `text` in the foreground color of the app-specific `token`
  # — the generic counterpart of {#active_border} for {#custom} tokens, and
  # the route for an app's own status-line chrome:
  #
  #   "q #{screen.theme.fg(:hint, "quit")}"   # => "q \e[38;5;245mquit\e[0m"
  #
  # The color is baked into the returned String, so text built this way does
  # *not* restyle on a {Screen#theme=} — rebuild it from
  # {Component#handle_theme_changed} instead.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def fg(token, text) = wrap(text, self[token], :fg)

  # Renders `text` on the background color of the app-specific `token`
  # — the generic counterpart of {#active_bg} for {#custom} tokens.
  # @param token [Symbol]
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  # @raise [KeyError] when the token is not present.
  def bg(token, text) = wrap(text, self[token], :bg)

  # Renders `text` on the {#active_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_bg(text) = wrap(text, active_bg_color, :bg)

  # Renders `text` in the {#active_border_color} foreground. Content
  # passes through verbatim, so it may embed non-SGR escapes (cursor
  # moves in a border string).
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def active_border(text) = wrap(text, active_border_color, :fg)

  # Renders `text` on the {#input_bg_color} background.
  # @param text [String]
  # @return [String] ANSI-rendered text, ending with an SGR reset.
  def input_bg(text) = wrap(text, input_bg_color, :bg)

  # The colors Tuile used before themes existed, tuned for dark terminal
  # backgrounds. GREY37 (palette 59) is what Rainbow emits for
  # `:darkslategray`; GREY27
  # (238, ~#444444) sits in the grayscale ramp, bright enough to stand
  # out against non-pure-black dark terminal themes (Gruvbox/Solarized/
  # OneDark base backgrounds sit in the #1d–#2d range) yet distinctly
  # darker than the active highlight at 59 (~#5f5f5f). The scrollbar reuses
  # GREY37, giving the handle the weight of the selection well and leaving
  # the sparser track glyph near-invisible.
  #
  # `error_color` is INDIAN_RED1 (203, ~#ff5f5f) rather than a pure RED1
  # (196): the message sits beside a field on the terminal's own background,
  # and the softer red keeps its contrast there while pure red vibrates.
  #
  # The error wells are palette 88 (~#870000) and LIGHT_PINK4 (95, ~#875f5f)
  # — split on lightness the way GREY27/GREY37 are, so the focused one is the
  # *lighter* well and the pair reads as a well rather than an alarm block.
  # Both survive `palette256` as themselves and stay distinct from each other
  # there, which is what keeps focus visible on an invalid field. The focused
  # well stays out of the bright mid-reds around #af5f5f: that is where
  # terminals put the cursor, and a caret sitting in an invalid field blurs
  # into a well of its own color.
  #
  # `placeholder_color` is GREY66 (248, ~#a8a8a8): dimmer than the terminal's
  # own foreground, so an empty field's hint reads as absent-value rather than
  # as typed text. It is the *dimmest* grey that still quantizes to `:white` on
  # a 16-color terminal — everything below 248 lands on `:bright_black`
  # alongside both wells, where the hint is not subtle but gone
  # (`design/decisions.md` `D_placeholder`).
  # @return [Theme]
  DARK = new(active_bg_color: Color::GREY37,
             active_border_color: Color::GREEN,
             input_bg_color: Color::GREY27,
             placeholder_color: Color::GREY66,
             error_color: Color::INDIAN_RED1,
             error_bg_color: Color.palette(88),
             error_active_bg_color: Color::LIGHT_PINK4,
             scrollbar_color: Color::GREY37)

  # Counterparts legible on light terminal backgrounds: grayscale-ramp
  # highlights just below white (GREY82 = 252 ~#d0d0d0, GREY85 = 253
  # ~#dadada — dark enough to read as a "well" against white, one step
  # lighter than the active highlight). `active_border_color` stays the
  # named green — named ANSI colors are remapped by the terminal's own
  # palette, so the theme picks a light-appropriate green for us. GREY62
  # (247, ~#9e9e9e) is the scrollbar: a *foreground* against pale, so it
  # goes a step darker than the highlights rather than matching them. RED3
  # (124, ~#af0000) is the error ink, dark for the same reason — the light
  # red {DARK} uses would wash out on white.
  #
  # The error wells are MISTY_ROSE1 (224, ~#ffd7d7) and LIGHT_PINK1 (217,
  # ~#ffafaf) — near-white tints that read as a well by *hue* rather than by
  # weight, and darken on focus as the grey pair does. 224 is the palest red
  # the 256-color palette holds: anything subtler quantizes onto the grey ramp
  # (`Color.hex("#ffeaea")` → 255) and the signal is gone entirely on a
  # 256-color terminal. It sits a shade *above* GREY85 rather than below it,
  # so an invalid field reads level with a valid one rather than more
  # recessed — the price of staying close to a white background.
  #
  # `placeholder_color` mirrors {DARK}'s rule from the other side: GREY62 (247,
  # ~#9e9e9e) is the *palest* grey that still quantizes to `:bright_black` on a
  # 16-color terminal, where both light wells are `:white`. It doubles as the
  # scrollbar ink, which wants the same thing — a foreground that recedes
  # against pale without vanishing into it.
  # @return [Theme]
  LIGHT = new(active_bg_color: Color::GREY82,
              active_border_color: Color::GREEN,
              input_bg_color: Color::GREY85,
              placeholder_color: Color::GREY62,
              error_color: Color::RED3,
              error_bg_color: Color::MISTY_ROSE1,
              error_active_bg_color: Color::LIGHT_PINK1,
              scrollbar_color: Color::GREY62)

  private

  # The single sanctioned place for verbatim SGR wrapping: `text` is not
  # parsed or validated, so callers may embed non-SGR escapes. Emits the
  # same bytes `StyledString.styled(text, ...).to_ansi` would for plain
  # text.
  # @param text [String]
  # @param color [Color]
  # @param target [Symbol] `:fg` or `:bg`.
  # @return [String]
  def wrap(text, color, target)
    "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
  end
end

Class Method Details

.chrome_token?(name) ⇒ Boolean

@param name — a token name.

@return — true iff name is a built-in chrome token (see CHROME_TOKENS) rather than a #custom one.

Parameters:

  • name (Symbol)

Returns:

  • (Boolean) 


146
 
# File 'lib/tuile/theme.rb', line 146

def self.chrome_token?(name) = CHROME_TOKENS.include?(name)

.ref(name) ⇒ Ref

Builds a Ref — a live theme reference for a late-resolved color slot like Component#bg_color=. Sugar for Theme::Ref.new(name).

@param name — a built-in chrome token (#input_bg_color etc.) or a #custom token name.

Parameters:

  • name (Symbol)

Returns:



153
 
# File 'lib/tuile/theme.rb', line 153

def self.ref(name) = Ref.new(name)

Instance Method Details

#[](token) ⇒ Color

Looks up an app-specific token from #custom.

@param token

Parameters:

  • token (Symbol)

Returns:



135
 
# File 'lib/tuile/theme.rb', line 135

def [](token) = custom.fetch(token)

#active_bg(text) ⇒ String

Renders text on the #active_bg_color background.

@param text

@return — ANSI-rendered text, ending with an SGR reset.

Parameters:

  • text (String)

Returns:

  • (String) 


215
 
# File 'lib/tuile/theme.rb', line 215

def active_bg(text) = wrap(text, active_bg_color, :bg)

#active_border(text) ⇒ String

Renders text in the #active_border_color foreground. Content passes through verbatim, so it may embed non-SGR escapes (cursor moves in a border string).

@param text

@return — ANSI-rendered text, ending with an SGR reset.

Parameters:

  • text (String)

Returns:

  • (String) 


222
 
# File 'lib/tuile/theme.rb', line 222

def active_border(text) = wrap(text, active_border_color, :fg)

#bg(token, text) ⇒ String

Renders text on the background color of the app-specific token — the generic counterpart of #active_bg for #custom tokens.

@param token

@param text

@return — ANSI-rendered text, ending with an SGR reset.

Parameters:

  • token (Symbol)
  • text (String)

Returns:

  • (String) 


210
 
# File 'lib/tuile/theme.rb', line 210

def bg(token, text) = wrap(text, self[token], :bg)

#fg(token, text) ⇒ String

Renders text in the foreground color of the app-specific token — the generic counterpart of #active_border for #custom tokens, and the route for an app's own status-line chrome:

"q #{screen.theme.fg(:hint, "quit")}"   # => "q \e[38;5;245mquit\e[0m"

The color is baked into the returned String, so text built this way does not restyle on a Screen#theme= — rebuild it from Component#handle_theme_changed instead.

@param token

@param text

@return — ANSI-rendered text, ending with an SGR reset.

Parameters:

  • token (Symbol)
  • text (String)

Returns:

  • (String) 


202
 
# File 'lib/tuile/theme.rb', line 202

def fg(token, text) = wrap(text, self[token], :fg)

#input_bg(text) ⇒ String

Renders text on the #input_bg_color background.

@param text

@return — ANSI-rendered text, ending with an SGR reset.

Parameters:

  • text (String)

Returns:

  • (String) 


227
 
# File 'lib/tuile/theme.rb', line 227

def input_bg(text) = wrap(text, input_bg_color, :bg)

#wrap(text, color, target) ⇒ String

The single sanctioned place for verbatim SGR wrapping: text is not parsed or validated, so callers may embed non-SGR escapes. Emits the same bytes StyledString.styled(text, ...).to_ansi would for plain text.

@param text

@param color

@param target — :fg or :bg.

Parameters:

  • text (String)
  • color (Color)
  • target (Symbol)

Returns:

  • (String) 


313
314
315
 
# File 'lib/tuile/theme.rb', line 313

def wrap(text, color, target)
  "#{color.to_ansi(target)}#{text}#{Ansi::RESET}"
end