# Concepts

## Background

SvSeeds was developed to help developers focus on application component functionality. By embedding SvSeeds components as "seeds" for common functionality, it provides an environment where developers can concentrate on what truly matters for their applications.

## Design Philosophy

### Standards-First Approach

Our fundamental philosophy is: **if standard HTML features are sufficient, use standard features instead of libraries**.
This approach is based on several key principles:

- Semantic HTML is recommended from an accessibility perspective
- Standard features provide familiar user experiences
- Native browser optimizations can be leveraged effectively

### Extending Standard Features

When standard features correspond to components, we build upon them as a foundation. For example:

- Disclosure component → Built on `details` and `summary` elements
- Modal component → Built on `dialog` element
- SelectField component → Built on `select` element

When no corresponding standard features exist, we build components from scratch while implementing proper accessibility support.

## Technical Features

### Headless Component Design

Based on the premise that styling requirements differ across projects, SvSeeds is designed as headless components that enable complete styling freedom.

### Separation of Functionality and Styling

For foundational components like buttons, we want to avoid the proliferation of similar component files within projects. To address this, SvSeeds adopts different approaches for **functionality** and **styling**:

#### Functionality: Structure Encapsulation

```svelte
<script>
  const options = new Map([
    ["1", "option1"],
    ["2", "option2"],
  ]);
</script>

<!-- Pattern we adopted -->
<SelectField {options} />
<!-- or -->
<ToggleGroupField>
  <ToggleGroup {options} />
</ToggleGroupField>

<!-- Pattern we didn't adopt -->
<Select.Root>
  <Select.Positioner>
    <Select.Content>
      {#each options.entries() as [value, label] (value)}
        <Select.Item key={value}>
          <Select.ItemText>{label}</Select.ItemText>
        </Select.Item>
      {/each}
    </Select.Content>
  </Select.Positioner>
</Select.Root>
```

By hiding internal structure from the outside:

- Code becomes easier to understand at a glance
- Custom component structure descriptions become simpler
- Eliminates the need for multiple component files with slightly different structures
- No need to be concerned with structure as long as it functions

This does not mean every component must be isolated. SvSeeds supports minimal nesting and composition where it clarifies ownership, such as placing a control inside its Field component or placing Disclosure children inside Accordion. The caller composes a small number of explicit children instead of describing a deep builder tree.

#### Styling: Complete Structure Access

Conversely, we provide access to all internal structures during styling:

- Enables detailed customization
- Minimizes constraints imposed by the library
- Eliminates the need for multiple component files with slightly different styles

To achieve this, we assign **part names** to each internal element, making them accessible during styling. Part names use abstract, unified naming for consistency.

A few components additionally include functional-only elements that are not part-named and do not appear in the component's Anatomy, such as a hidden `<input type="hidden">` used solely for form submission. These are neither styling nor user-control targets; they exist purely to make the control work.

### Variant-based Styling

To reduce the complexity of switching styling based on conditions, we provide functionality that automatically applies predefined styling based on component variants:

- Toggle button on/off variants
- Text input validation failure variants
- Other dynamic variant changes

This is achieved by giving each component variant properties and building a system that can apply styles defined for each variant.

### Library Components as Project Files

There are cases where you only need specific components. Adding an entire UI library to your project just for a few components can be excessive overhead. Additionally, there may be times when you want to make minor modifications to the internal workings of library components. By treating library components as files within your project, we can address these needs. Therefore, we've prepared a CLI tool that allows you to add components directly to your project.

## Summary

SvSeeds is a Svelte UI library that balances modern development requirements for functionality and customizability while respecting standard technologies. Through our approach of "hide functionality, expose styling," we provide an environment where developers can focus on the value creation they should be concentrating on.