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/Component-by-Component-Concerns.md

@@ -0,0 +1,329 @@
+# Component-by-Component Concerns
+
+This matrix captures likely API/DX complaints per component area, including potential improvement directions.
+
+## Display Components
+
+### Alert
+
+Concerns:
+- Variant as magic string.
+- Content/title may be used as raw HTML without explicit safety boundary.
+- Custom classes/attributes may be inconsistent.
+
+Potential improvements:
+- Enum for variant.
+- Safe text API + explicit trusted HTML path.
+- Standard `className` and `attributes`.
+
+### Avatar
+
+Concerns:
+- Fallback/shape/size options can become string-heavy.
+- Accessibility attributes may be awkward without attr bag.
+
+Potential improvements:
+- Typed size/shape options.
+- Uniform attributes model.
+
+### Badge
+
+Concerns:
+- Variant string typing and typo risk.
+- Inconsistent extension points compared with Button/Input.
+
+Potential improvements:
+- Variant enum/constants.
+- Standardized extensibility surface.
+
+### Breadcrumb
+
+Concerns:
+- Item model may be primitive/string-only.
+- Accessibility hooks and custom attrs may be limited.
+
+Potential improvements:
+- Named item record model.
+- Attr bag and aria convenience options.
+
+### Card
+
+Concerns:
+- Raw HTML sections can be misused.
+- Optional sections create many constructor parameters.
+
+Potential improvements:
+- Options record.
+- Safe content model.
+
+### Progress
+
+Concerns:
+- Value bounds validation may be implicit or absent.
+- Class extension inconsistencies.
+
+Potential improvements:
+- Explicit min/max validation.
+- Standard class and attr extension.
+
+### Separator
+
+Concerns:
+- Orientation/type as magic string.
+- Thin API extensibility for accessibility semantics.
+
+Potential improvements:
+- Enum for orientation.
+- Attr bag support.
+
+### Skeleton
+
+Concerns:
+- Shape/sizing patterns vary by caller wrappers.
+- Lacks compositional guidance for complex placeholders.
+
+Potential improvements:
+- Preset variants + className override.
+- Pattern docs for loading states.
+
+### Table
+
+Concerns:
+- Primitive row/cell string model limits rich content.
+- Possible heavy constructor precomputation for large data.
+- Safety boundary unclear when rendering rich cell content.
+
+Potential improvements:
+- Typed column/cell models.
+- Lazy render/cache strategy for large tables.
+- Explicit text-vs-html cell APIs.
+
+### Tooltip
+
+Concerns:
+- Trigger/content composition can rely on string/slot conventions.
+- Accessibility and focus behavior may need clearer guidance.
+
+Potential improvements:
+- Better keyboard and aria documentation.
+- Attr/class pass-through consistency.
+
+## Form Components
+
+### Button
+
+Concerns:
+- Variant/size/type magic strings.
+- `hxAttrs` raw string ergonomics/security risk.
+- Need for wrapper to add layout classes in some contexts.
+
+Potential improvements:
+- Enums/constants.
+- Structured attributes.
+- Standard `className`.
+
+### Checkbox
+
+Concerns:
+- Label/id/checked model may not match other form controls.
+- Limited pass-through attributes.
+
+Potential improvements:
+- Shared form-control options contract.
+- Attr bag and validation state support.
+
+### FileInput
+
+Concerns:
+- Accepted file types and attrs may be cumbersome.
+- Inconsistent API vs Input/Textarea.
+
+Potential improvements:
+- Shared form-control options.
+- Better file-specific typed options.
+
+### Input
+
+Concerns:
+- Input type as string.
+- Validation/aria hooks likely manual.
+
+Potential improvements:
+- Input type enum/constants.
+- Baseline form options and attr bag.
+
+### RadioGroup
+
+Concerns:
+- Tuple options reduce readability.
+- Direction/layout often string-based.
+- Attr pass-through likely limited.
+
+Potential improvements:
+- Named option record.
+- Typed direction values.
+- Standard form/attr contract.
+
+### Select
+
+Concerns:
+- Option model and selected/default semantics may be inconsistent.
+- Styling/attrs may differ from Input/Textarea.
+
+Potential improvements:
+- Named option record.
+- Unified form control API.
+
+### Slider
+
+Concerns:
+- Value/min/max/step validation and formatting ergonomics.
+- Limited attr/class extensibility in some usages.
+
+Potential improvements:
+- Stronger numeric validation and docs.
+- Standard extension points.
+
+### Switch
+
+Concerns:
+- Checked/value semantics may differ from checkbox.
+- JS and accessibility contracts may not be obvious.
+
+Potential improvements:
+- Form contract alignment.
+- Explicit a11y + JS requirements docs.
+
+### Textarea
+
+Concerns:
+- Similar concerns to Input: attrs, validation, and consistency.
+
+Potential improvements:
+- Shared baseline form options.
+
+## Interactive Components
+
+### Accordion
+
+Concerns:
+- Tuple-based item model.
+- JS selector coupling via markup classes/data attributes.
+- Rich content safety boundary if strings are HTML.
+
+Potential improvements:
+- Named `AccordionItem` model.
+- Stable data-role contracts.
+- Explicit safe/trusted content APIs.
+
+### Calendar
+
+Concerns:
+- JS dependency and date contract coupling.
+- Limited custom attributes for instrumentation/a11y.
+
+Potential improvements:
+- Explicit JS contract docs in API comments.
+- Standard attrs support.
+
+### CalendarRange
+
+Concerns:
+- Similar to Calendar plus complexity around range state.
+- Validation/error state API may be weak.
+
+Potential improvements:
+- Strong state model and docs.
+- Better attr/validation contract.
+
+### Dialog
+
+Concerns:
+- Open/close semantics rely on data attributes and JS wiring.
+- Content sections may use raw HTML strings.
+
+Potential improvements:
+- Named trigger/actions patterns in docs.
+- Safe content APIs and structured attrs.
+
+### DropdownMenu
+
+Concerns:
+- Item model can be tuple-heavy.
+- Keyboard and accessibility behavior depends on JS contract.
+
+Potential improvements:
+- Named item/action records.
+- Explicit interaction/accessibility contract docs.
+
+### Tabs
+
+Concerns:
+- Tuple-based tab definitions.
+- ID/active state handling as plain strings.
+- JS contract may be implicit.
+
+Potential improvements:
+- `TabItem` record + typed active key model.
+- Explicit JS and accessibility notes.
+
+### TimePicker
+
+Concerns:
+- Value format/string handling may be error-prone.
+- JS coupling and validation ergonomics.
+
+Potential improvements:
+- Typed time value helpers.
+- Clear formatting and validation rules.
+
+## Notification Components
+
+### Toast
+
+Concerns:
+- Trigger lifecycle and JS coupling may not be obvious.
+- Variant/style options likely string-based.
+
+Potential improvements:
+- Typed options and JS contract docs.
+- Standard attrs/class extension points.
+
+### ToastViewport
+
+Concerns:
+- Placement/config likely string-heavy.
+- Global singleton usage constraints may be under-documented.
+
+Potential improvements:
+- Typed placement/options.
+- Clear singleton/layout guidance.
+
+## Navigation Components
+
+### Pagination
+
+Concerns:
+- Data model may be primitive and hard to customize.
+- Accessibility state semantics need consistency.
+
+Potential improvements:
+- Named model for page items and actions.
+- Strong accessibility defaults and hooks.
+
+## Cross-Component Cost Notes
+
+Low-cost improvements:
+- Better docs for limitations/security/js contracts.
+- Add design guidelines and migration policy.
+- Constants for common string literals.
+
+Medium-cost improvements:
+- Standard `className` and `attributes` options.
+- Options records for complex constructors.
+- Named item models replacing tuples.
+
+High-cost improvements:
+- Safe-by-default content model transition.
+- Full enum migration for all semantic options.
+- Analyzer suite for API misuse detection.