design-systems and themes

[amitu]

Package Types

We have a bunch of different kinds of packages.

• content package (main package) (main: true): these provide content (someone adds them as a dependency to remix content)
• app packages: these provide full web apps that one can install (they provide URLs) (app: $app-spec)
• design-system package: they define what are the names of colours, how many fonts are used, main ui elements like buttons etc (design-system: true)
• theme package: they provide specific values to colours / fonts etc defined in design-system package. every theme package has a corresponding design system package. (theme: <name of the design system>)
• font package: to wrap a font file into fastn package (font-package: true)
• typography package: theme must ideally not define actual typography in its own, but keep it in a separate package, so other themes can easily mix and match typography. technically this is possible even if theme itself provides typography module also (typography-package: true)
• color-scheme package (color-scheme: true)
• soon to come: code highlight package (syntax-theme: true)
• syntax-grammar package: someone creates a new language and they want to add it to fastn they have to create this kind of package.
• category package: these are interface modules, defining one or more components. Eg business-card, pricing-card, wedding-invitation-card, headers, footers. (category: true)
• flavour package: flavours "implement a category package" (flavour: <name-of-category>)
• auth package: this can be used to implement auth logic, eg login with this new startup (auth: $auth-spec)

Design System

Design system kinds of splits the universe, every package has to chose a design system, and two packages using the same design system can co-exist easily. So design system becomes a property of fastn.package. And since we are trying to bless one design system, this property is optional, and default value is the blessed design system. So far in 0.4 we can only have one design system, codified in ftd.color-scheme etc types. But we are going to move these types from fastn to a design system community package, eg: fastn-community.github.io/design-system (ds for now) is our blessed design system.

ds will provide ds.page (UI elements), ds.color-scheme (design related variables), etc.

Theme

Lets say there exists a theme called fastn-community.github.io/midnight-storm, which "implements" fastn-community.github.io/design-system, and provides same set of "ds.page (UI elements), ds.color-scheme (design related variables), etc." etc, but the actual UI element could look different, or design system variables may be different.

-- import: fastn
-- fastn.package: foo
theme: foo/ds ;; design-system key is omitted so we are using the default `ds` design system

-- fastn.dependency: some-component-library
theme: foo/ds ;; this is default behaviour

Whatever is the theme defined by fastn.package, will get passed to all dependencies by default, so the last line with theme can be omitted.

Using packages from different design system universes in same content package

Some content package may want that, so they can do this:

-- import: fastn
-- fastn.package: weird-package
design-system: <weird-package's-default-design-system> 
theme: weird-package/ds-1

-- fastn.dependency: weird-package's-default-design-system
-- fastn.dependency: weird-package's-secondary-design-system

-- fasnt.dependency: some-dep-from-default-design-system-universe
theme:  weird-package/ds-1 ;; optional line

-- fastn.dependncy: some-dep-from-secondary-design-system-universe
theme: weird-package/ds-2 ;; required 
;; (ds-2 must re-export all symbols needed by secondary design system)

[amitu]

By default every package will have a global variable ds available to them. This will have type fastn-community.github.io/design-system and alias is ds. Its as if the package has written this:

-- import: fastn
-- fastn.package: foo-dep
design-system: fastn-community.github.io/design-system as ds

When they leave out design-system configuration.

One can overwrite this by explicitly adding design-system: in their fastn.package:

-- import: fastn
-- fastn.package: foo-dep
design-system: fastn-community.github.io/design-system as the-ds
;; if you want a different design system altogether 
;; design-system: some-other-design-system as ds 

[amitu]

With this setup, when the dependency code is using ds, it does not get fastn-community.github.io/design-system, but midnight-storm if the content package that is using it has said:

-- import: fastn
-- fastn.package: foo
theme: fastn-community.github.io/midnight-storm

-- fastn.dependency: fastn-community.github.io/midnight-storm
-- fastn.dependency: foo-dep