chore(openspec): archive design-source-abstraction, sync specs

Sync 4 delta specs to main: design-source-protocol (new),
source-dispatch (new), configuration (updated),
tokens-file-source (updated). Archive completed change.

Author: alexey1312

…design-source-abstraction/.openspec.yaml …design-source-abstraction/.openspec.yamlopenspec/changes/design-source-abstraction/.openspec.yaml renamed to openspec/changes/archive/2026-03-21-design-source-abstraction/.openspec.yaml openspec/changes/design-source-abstraction/.openspec.yaml renamed to openspec/changes/archive/2026-03-21-design-source-abstraction/.openspec.yaml

@@ -1,147 +1,98 @@
-# Configuration
-
-Default values and constraints for PKL configuration schemas.
-
 ## ADDED Requirements
 
-### Requirement: iOS default values
-
-iOS PKL schema SHALL provide sensible default values for commonly used fields to reduce boilerplate in configuration files.
-
-#### Scenario: iOS ColorsEntry defaults
-
-- **WHEN** an iOS ColorsEntry does not specify `useColorAssets`
-- **THEN** the system SHALL use `true` as the default value
-
-#### Scenario: iOS ColorsEntry nameStyle default
-
-- **WHEN** an iOS ColorsEntry does not specify `nameStyle`
-- **THEN** the system SHALL use `"camelCase"` as the default value
-
-#### Scenario: iOS IconsEntry defaults
-
-- **WHEN** an iOS IconsEntry does not specify `format`
-- **THEN** the system SHALL use `"pdf"` as the default value
-
-#### Scenario: iOS IconsEntry assetsFolder default
-
-- **WHEN** an iOS IconsEntry does not specify `assetsFolder`
-- **THEN** the system SHALL use `"Icons"` as the default value
-
-#### Scenario: iOS ImagesEntry scales default
-
-- **WHEN** an iOS ImagesEntry does not specify `scales`
-- **THEN** the system SHALL use `[1, 2, 3]` as the default value
-
-#### Scenario: iOS ImagesEntry format defaults
-
-- **WHEN** an iOS ImagesEntry does not specify `sourceFormat` or `outputFormat`
-- **THEN** the system SHALL use `"png"` as the default for both
-
-#### Scenario: iOS iOSConfig xcassetsInMainBundle default
-
-- **WHEN** an iOSConfig does not specify `xcassetsInMainBundle`
-- **THEN** the system SHALL use `true` as the default value
-
-### Requirement: Android default values
-
-Android PKL schema SHALL provide sensible default values for commonly used fields.
-
-#### Scenario: Android ImagesEntry format default
-
-- **WHEN** an Android ImagesEntry does not specify `format`
-- **THEN** the system SHALL use `"png"` as the default value
-
-#### Scenario: Android IconsEntry nameStyle default
-
-- **WHEN** an Android IconsEntry does not specify `nameStyle`
-- **THEN** the system SHALL use `"snake_case"` as the default value
-
-#### Scenario: Android ImagesEntry scales default
-
-- **WHEN** an Android ImagesEntry does not specify `scales`
-- **THEN** the system SHALL use `[1, 1.5, 2, 3, 4]` as the default value
-
-#### Scenario: Android ThemeAttributes defaults
+### Requirement: SourceKind typealias in Common.pkl
 
-- **WHEN** ThemeAttributes does not specify `attrsFile`, `stylesFile`, `stylesNightFile`
-- **THEN** the system SHALL use `"values/attrs.xml"`, `"values/styles.xml"`, `"values-night/styles.xml"` respectively
+The `Common.pkl` schema SHALL define a `SourceKind` typealias:
 
-### Requirement: Flutter default values
+```pkl
+typealias SourceKind = "figma"|"penpot"|"tokens-file"|"tokens-studio"|"sketch-file"
+```
 
-Flutter PKL schema SHALL provide sensible default values for commonly used fields.
+#### Scenario: Valid sourceKind values accepted
 
-#### Scenario: Flutter ColorsEntry className default
+- **WHEN** a PKL config sets `sourceKind = "figma"`
+- **THEN** PKL evaluation SHALL succeed
 
-- **WHEN** a Flutter ColorsEntry does not specify `className`
-- **THEN** the system SHALL use `"AppColors"` as the default value
+#### Scenario: Invalid sourceKind rejected
 
-#### Scenario: Flutter ImagesEntry scales default
+- **WHEN** a PKL config sets `sourceKind = "unknown"`
+- **THEN** PKL evaluation SHALL fail with a validation error
 
-- **WHEN** a Flutter ImagesEntry does not specify `scales`
-- **THEN** the system SHALL use `[1, 2, 3]` as the default value
+### Requirement: sourceKind field in FrameSource
 
-### Requirement: Web default values
+The `FrameSource` open class in `Common.pkl` SHALL include an optional `sourceKind` field:
 
-Web PKL schema SHALL provide sensible default values for commonly used fields.
+```pkl
+open class FrameSource extends NameProcessing {
+    sourceKind: SourceKind?
+    // ... existing fields
+}
+```
 
-#### Scenario: Web IconsEntry defaults
+When `sourceKind` is `null`, the system SHALL default to `"figma"`.
 
-- **WHEN** a Web IconsEntry does not specify `iconSize`
-- **THEN** the system SHALL use `24` as the default value
+#### Scenario: FrameSource without sourceKind defaults to figma
 
-#### Scenario: Web IconsEntry generateReactComponents default
+- **WHEN** an icons entry does not specify `sourceKind`
+- **THEN** the system SHALL treat it as `sourceKind = "figma"`
 
-- **WHEN** a Web IconsEntry does not specify `generateReactComponents`
-- **THEN** the system SHALL use `true` as the default value
+#### Scenario: FrameSource with explicit sourceKind
 
-### Requirement: Common and Figma default values
+- **WHEN** an icons entry specifies `sourceKind = "penpot"`
+- **THEN** the system SHALL use `"penpot"` as the source kind for that entry
 
-Common and Figma PKL schemas SHALL provide sensible default values.
+### Requirement: sourceKind field in VariablesSource
 
-#### Scenario: Cache defaults
+The `VariablesSource` open class in `Common.pkl` SHALL include an optional `sourceKind` field:
 
-- **WHEN** a Cache config does not specify `enabled` or `path`
-- **THEN** the system SHALL use `false` and `".exfig-cache.json"` respectively
+```pkl
+open class VariablesSource extends NameProcessing {
+    sourceKind: SourceKind?
+    // ... existing fields
+}
+```
 
-#### Scenario: Figma timeout default
+When `sourceKind` is `null`, the system SHALL auto-detect:
 
-- **WHEN** a FigmaConfig does not specify `timeout`
-- **THEN** the system SHALL use `30` seconds as the default value
+- If `tokensFile` is set → `.tokensFile`
+- Otherwise → `.figma`
 
-### Requirement: PKL constraints for required string fields
+#### Scenario: VariablesSource auto-detects tokensFile
 
-PKL schemas SHALL validate that required string fields are not empty using `!isEmpty` constraint.
+- **WHEN** a colors entry has `tokensFile` set but `sourceKind` is null
+- **THEN** the system SHALL use `tokensFile` as the source kind
 
-#### Scenario: Empty xcodeprojPath rejected
+#### Scenario: VariablesSource auto-detects figma
 
-- **WHEN** a PKL config specifies `xcodeprojPath = ""`
-- **THEN** `pkl eval` SHALL fail with a constraint violation error
+- **WHEN** a colors entry has no `tokensFile` and `sourceKind` is null
+- **THEN** the system SHALL use `figma` as the source kind
 
-#### Scenario: Empty tokensFileId rejected
+#### Scenario: Explicit sourceKind overrides auto-detection
 
-- **WHEN** a PKL config specifies `tokensFileId = ""`
-- **THEN** `pkl eval` SHALL fail with a constraint violation error
+- **WHEN** a colors entry has `sourceKind = "tokens-studio"` and no `tokensFile`
+- **THEN** the system SHALL use `tokens-studio` as the source kind regardless of auto-detection
 
-### Requirement: PKL constraints for numeric ranges
+#### Scenario: Explicit sourceKind takes priority over tokensFile presence
 
-PKL schemas SHALL validate numeric fields with appropriate range constraints.
+- **WHEN** a colors entry has `sourceKind = "figma"` AND `tokensFile` is also set
+- **THEN** the system SHALL use `figma` as the source kind (explicit overrides auto-detection)
+- **NOTE:** This handles the case where a user switches back from tokens-file to figma without removing the `tokensFile` field
 
-#### Scenario: Figma timeout range
+### Requirement: PKL codegen produces DesignSourceKind bridging
 
-- **WHEN** a PKL config specifies `timeout = 0`
-- **THEN** `pkl eval` SHALL fail with a constraint violation error
+After running `./bin/mise run codegen:pkl`, the generated Swift types SHALL include `SourceKind` as a String-based enum. The ExFig-* platform entry types SHALL bridge PKL `SourceKind` to ExFigCore `DesignSourceKind`.
 
-#### Scenario: Valid Figma timeout
+#### Scenario: PKL SourceKind bridges to Swift DesignSourceKind
 
-- **WHEN** a PKL config specifies `timeout = 60`
-- **THEN** `pkl eval` SHALL succeed
+- **WHEN** a PKL config with `sourceKind = "tokens-file"` is evaluated
+- **THEN** the generated Swift value SHALL be bridged to `DesignSourceKind.tokensFile`
 
-### Requirement: Defaults do not change generated Swift code
+### Requirement: Backward compatibility
 
-Adding default values to PKL schemas SHALL NOT change the generated Swift types (`codegen:pkl` output).
+All existing PKL configs without `sourceKind` fields SHALL continue to work without modification. The field is optional with null default, and null maps to auto-detected behavior (figma for FrameSource, figma-or-tokensFile for VariablesSource).
 
-#### Scenario: Zero diff after codegen
+#### Scenario: Existing config without sourceKind
 
-- **WHEN** `./bin/mise run codegen:pkl` is run after adding defaults to PKL schemas
-- **THEN** the generated `Sources/ExFigConfig/Generated/*.pkl.swift` files SHALL have zero diff
+- **WHEN** an existing `exfig.pkl` config with no `sourceKind` fields is evaluated
+- **THEN** PKL evaluation SHALL succeed
+- **AND** export behavior SHALL be identical to the current implementation