Added issues that are going to be tracked and will be deeply considering changes based on DX.

Co-authored-by: Copilot <copilot@github.com>

docs/Issues/Improvement-Options-and-Costs.md

@@ -0,0 +1,68 @@
+# Improvement Options and Costs
+
+This matrix helps prioritize API improvements by DX value, risk, and migration cost.
+
+Legend:
+
+- Effort: S (small), M (medium), L (large), XL (very large)
+- Break Risk: Low, Medium, High
+- Runtime Impact: Positive, Neutral, Slight Negative
+
+| Proposal | Solves | Effort | Break Risk | Runtime Impact | Notes |
+|---|---|---|---|---|---|
+| Add standardized `className` to all components | wrapper-div workaround, styling consistency | M | Low | Neutral | Additive change if optional |
+| Add standardized attributes bag (`attributes`) | missing `aria-*`, `data-*`, test IDs | L | Medium | Slight Negative | Best long-term extensibility |
+| Keep `hxAttrs` as compatibility fallback | migration safety | S | Low | Neutral | Mark as legacy in docs |
+| Enums for variant/size/type | magic strings | M | Medium | Neutral | Better compile-time safety |
+| Constants classes for allowed string values | magic strings (partial) | S | Low | Neutral | Good transitional step |
+| Replace tuple APIs with named records | readability, future extensibility | M | Medium | Neutral | `TabItem`, `AccordionItem`, etc. |
+| Add options-record constructors for complex components | constructor bloat | M | Low | Neutral | Improves call-site clarity |
+| Safe-by-default text encoding APIs | XSS risk | M | High | Neutral | Breaking if current raw HTML behavior is relied on |
+| Explicit trusted HTML wrapper API | intentional raw HTML path | M | Medium | Neutral | Clear security intent |
+| Add standardized Security section in every component doc | security docs inconsistency | M | Low | Neutral | High ROI docs work |
+| Add standardized Accessibility section in every component doc | a11y gaps | M | Low | Neutral | High ROI docs work |
+| Add JS contract metadata/docs for interactive components | hidden JS dependencies | S | Low | Neutral | Immediate debugging benefit |
+| Add development-time JS diagnostics in components.js | silent interactive failures | M | Low | Slight Negative | Dev-only checks recommended |
+| Add analyzer: invalid variant literals | magic string typos | L | Low | Neutral | Tooling investment pays off |
+| Add analyzer: unsafe unencoded user input usage | XSS prevention | L | Medium | Neutral | Requires careful heuristics |
+| Add API evolution policy and deprecation plan | change management | S | Low | Neutral | Needed before major refactors |
+| Introduce per-category baseline contracts | inconsistency across components | L | Medium | Neutral | Strategic but broad |
+| Introduce table column/cell model | table API limitations | L | Medium | Neutral | High payoff for real apps |
+| Add form control baseline contract | form component inconsistency | L | Medium | Neutral | Improves predictability |
+| Introduce lazy compute in heavy components | precompute allocation concerns | M | Low | Positive | Benchmark before and after |
+
+## Recommended Sequencing
+
+1. Documentation-first, no-break improvements:
+- known limitations docs
+- security/a11y/js contract sections
+- issue tracker links and migration guidance
+
+2. Additive API upgrades:
+- `className`
+- `attributes`
+- options records
+- constants for allowed values
+
+3. Strong typing and validation:
+- enums
+- analyzers
+- debug validations
+
+4. Breaking/security-hardening updates:
+- safe-by-default content model
+- deprecate raw string HTML entry points
+
+## Consequence Summary
+
+Positive consequences:
+- More predictable and discoverable API
+- Lower bug rate from string typos and attr mistakes
+- Better security baseline
+- Less wrapper-div boilerplate
+
+Negative/neutral consequences:
+- Larger API surface
+- Migration overhead in existing usages
+- Potentially more allocations for flexible attribute models
+- Need for contributor discipline to maintain consistency