Locations of touchy resources with themes

[pylapp]

Context

Depending to some themes, we may face a tricky situation where some fonts (WOFF or TTF files) must be used but not exposed externaly in a public repository (even if fonts are extractable from binaries or websites duh!).
For some case a simple "NOTICE" file update precising the files are proprietary with the suitable license and copyrights is enough.
But for other cases it is not enough.

Today our technical stack is this one:

• a public open source GitHub project for the Swift Package
• a public open source GitHub project for the design system toolbox app
• an internal GitLab project compiling the design system toolbox app, initialy to keep internal the provisiong profiles and certificates

Note

With the Sosh theme implementation we had the agreement of the Brand to use and keep public the Sosh theme and its fonts files.
We asked it if in any case in the future we will have to use internal resources, and we had confirmation it won't be the case:
things can be public and will remain external.

Note

Both library and app must be open source to easy contributions because without design system toolbox app available users won't be able to contribute with pair of pull requests and provide tests etc.

Conclusion

Tip

TL ; DR Go to solution F. Or otherwise E. Touchy assets likes fonts or icons can be found from websites or extracted from apps. Why wasting so much energy trying hiding them? Spliting themes in internals repos breaks documentations, increase diffiiculties to maintain everything, break tokenator.
One pilar of OUDS is to provide open source and public assets for brands, affiliates, subcontrators and all entities.

Note

A compromise can be to assume some themes won't be tested and exposed as they are in the Swift package and design system toolbox.
For example we can have like other libs the app public and the design system implementation in an open source library.
Developers are always able to define their own themes wherever the repository in use is hosted.

If a theme must use touchy resources, we can define the theme in the public repository (like we do today), test it in the design system toolbox app but let the users add their own fonts and resources.
It will prevent the core maintainers to manage too much repositories and keep theme and demo app external.

Note

For example with have today with v0.17.0 an Orange theme for Orange products and affiliates.
If there is a need to use a specific font which cannot be made public, the developers with this need can just use the current Orange theme and load the fonts to it. Or create their own theme based on the Orange one.
But these resources won't be in the public repo because not authorized, and not tested by core maintainers.

flowchart TD
%% Nodes
    A("Core maintainers provide OUDS Swift Package")
    B("Does the theme has touchy resources?")
    C("Use the theme as is in the app")
    D("Does an exising theme mathing almost the needs exist?")
    E("Subclass existing theme or compose it to load touchy resource outside OUDS repos")
    F("Create fresh new theme outside OUDS repos")
    G("Use the custom theme in the app")

    
%% Edge connections between nodes
    A --> B
    B -- NO --> C
    B -- YES --> D
    D -- YES --> E
    D -- NO --> F
    E --> G
    F --> G
    
%% Individual node styling

%% Green for public external repos
    style A color:#FFFFFF, stroke:#00C853, fill:#00C853
    style C color:#FFFFFF, stroke:#00C853, fill:#00C853

    %% Blue for private internal repos
    style E color:#FFFFFF, stroke:#2962FF, fill:#2962FF
    style F color:#FFFFFF, stroke:#2962FF, fill:#2962FF

Loading

Issues

• 1️⃣ How can we define a theme with these touchy resources?
• 2️⃣ How can we thus use some touchy resources for the snapshots tests and keep theme updated?
• 3️⃣ How can we let users use their touchy resources?
• 4️⃣ How can we preserve the users experience and our own maintainers experience?
• 5️⃣ How can we keep updated the documentation?
• 6️⃣ What are the impacts on tokenator?
• 7️⃣ How to keep things open source and clear?

Solutions proposals

A - Design system toolbox app internal, theme using touchy resources external, but touchy resources internal

Description

We can have the demo app internal embeding the external theme but with touchy resources internal. However the migration from GitHub is a bit heavy (see below).

We can keep updated snapshots for tests with the touchy resources applied because the app is internal and in the same network as the resources, so everything can compile and make us able to have updated snapshots.

However it implies to define a solution to load to a theme the touchy resources to use if the theme definition is in the public repo.

About issues

• 1️⃣ Theme must be able to load touchy resources elsewhere, i.e. from the app in use
• 2️⃣ ❌ In that case the snapshots tests can be still updated because app has the touchy resources and apply them to the theme, under same network but people without access to this network won't be able to build and tests
• 3️⃣ Users thus will be able to load their touchy resources
• 4️⃣ ❌ If well documented quite simple for users, boring for maintainers to use several forges
• 5️⃣ ✅ Documentation not broken
• 6️⃣ ✅ No impact on tokenator
• 7️⃣ ❌ Design system toolbox app won't be open source anymore, not possible to get contributions

Conclusion

Caution

Too much bad points: iOS will be the only project without public showcase, this app must be open source,
lib maintainers will have to deal with two forges (GitHub for Swift Package, GitLab for showcase app)
and at least four repos (lib, app, resources, app distribution). The app distribution and the app projects can be merged reducing to three repos but it is still heavy.

B - Design system toolbox app internal, theme and touchy resources internal

Description

We can have the demo app internal embeding the touchy resources. However the migration from GitHub is a bit heavy (see below).

We will have to deal with at least four repositories to define the theme with the touchy resources (one repo for the Swift Package, one repo for the demo app, as many repos as themes with touchy resources, one repo for app distribution). Maintaining several repositories can be costly overall if themes contracts changed etc. In addition the themes definitions are open source to let subcontractors and affiliates use them. So if the themes are internal but open source it is a non sense and nothing will preventing users to misunderstand they cannot publish the resources.

About issues

• 1️⃣ Simple, theme will embed its own touchy resources (like Orange, Sosh and Wireframe themes today)
• 2️⃣ ❌ Snapshots tests will be updated because everything in same network and compiles
• 3️⃣ Users not able to load their touchy resources (in that case no need to implement this evolution)
• 4️⃣ ❌ Transparent for users but painful for maintainers
• 5️⃣ ❌ Documentation is broken as not possible to build it from outside for internal Swift packages!
• 6️⃣ ❌ Tokenator broken as unable to manage several rep
• 7️⃣ ❌ Design system toolbox app won't be open source anymore, not possible to get contributions

Conclusion

Caution

Too much bad points: iOS will be the only project without public showcase, whi must be open source,
Swift package maintainers will have to deal with two forges (GitHub for Swift Package, GitLab for showcase app)
and at least four repos (lib, app, resources, app distribution). The app distribution and the app projects can be merged but working with three repos is still heavy.
But documentation will be broken: it won't be possible to build a unified documentation with content private or internal.
And tokenator is not able to manage several destination repos.

Tip

But people wanting themes with such touchy resources can define their own theme, e.g. by subclassing the Orange theme
and use the forge they want.

C - Design system toolbox app external, theme external, touchy resources external but private

Description

Maybe we can define a solution where the touchy resources are in a private repository on GitHub. Thus, with crendentials, demo app can be built with a reference to this repository and snapshot tests updated. However things must be updated and documented to let users integrate their touchy resources for the theme. And people wanting to build the demo app won't be able if they do not have access to the private repositories. In addition it means the theme in the Swift package won't have these assets.

About issues

• 1️⃣ Theme must be able to load touchy resources elsewhere, i.e. from the app in use
• 2️⃣ ❌ In that case the snapshots tests can be still updated because app has the touchy resources and apply them to the theme, under same network
• 3️⃣ Users thus will be able to load their touchy resources
• 4️⃣ ❌ If well documented quite simple for users but boring for maintainers
• 5️⃣ ✅ Documentation not broken
• 6️⃣ ✅ No impact on tokenator
• 7️⃣ ❌ Design system toolbox app may not compile anymore for people wating to contribute if they do not have credentials

Caution

People without access to the private repo won't get the assets and won't be able to compile.
Having private repos in GitHub Orange-OpenSource is not compliant.
Not comfortable to work with 3 repos repos.

D - Download touchy resources outside

Description

It is a bit hacky, but we can define a script which will download from for example a website the font files and add it to the app. Then the font files must be registered in the app and tests be still updated. However is means the theme in the Swift package won't have these assets.

About issues

• 1️⃣ Theme must be able to load touchy resources elsewhere, i.e. from the app in use
• 2️⃣ ❌ In that case the snapshots tests can be still updated because app has the touchy resources and apply them to the theme, under same network
• 3️⃣ Users thus will be able to load touchy resources
• 4️⃣ ❌ If well documented quite simple for users but hazardous for maintainers and has security risks with external side loading
• 5️⃣ ✅ Documentation not broken
• 6️⃣ ✅ No impact on tokenator
• 7️⃣ ✅ Design system toolbox app still open source

Caution

Hacky, not trustable, hazardous to load touchy resources elsewhere, need to check their integrity, themes won't embed their resources

E - Design system toolbox app external, theme external, touchy resources internal

Description

We can consider keeping the internal project to build the demo app, let external public the themes definitions and let the demo app project also external public. Thus no changes required for our CI/CD, tests can be run and projects cloned by anyone.
In addidition we can enhance the API to let users load the touchy resources they need like fonts. For example in their app project when the instanciate the theme they can in the same time load fonts and register the assets hosted in their app from their repos.
Thus we wont embed maybe heavy assets for only one theme and increase the size of the repo and perhaps the size of the lib.

About issues

• 1️⃣ Theme must be able to load touchy resources elsewhere, i.e. from the app in use
• 2️⃣ ✅ In that case the snapshots tests can be used but without these assets. A bit sad for typography.
• 3️⃣ Users thus will be able to load their touchy resources
• 4️⃣ ✅ If well documented quite simple for users but and not costly for maintainers
• 5️⃣ ✅ Documentation not broken
• 6️⃣ ✅ No impact on tokenator
• 7️⃣ ✅ Design system toolbox app still open source

Tip

This solution is quite good.
No changes in repos, no complexity handeling more and more projects in several forges.
No need to always embed fonts or heavy resources.
Users can simply load the touchy assets through the API from their app.
Indeed snapshots tests won't catch regressions on typography but they still work for all the other topics.

F - Design system toolbox app external, theme and touchy resources external

Description

OUDS provides themes. Themes is defined by tokens, icons, fonts, touchy ressources.
Even for fonts it is possible to extract the file from a website of apps.
We can consider keeping everything external and public. Thus no changes required for our CI/CD, tests can be run and projects cloned by anyone.
In addidition we can enhance the API to let users load the touchy resources they need like fonts. For example in their app project when the instanciate the theme they can in the same time load fonts and register the assets hosted in their app from their repos.
Thus we wont embed maybe heavy assets for only one theme and increase the size of the repo and perhaps the size of the lib.

About issues

• 1️⃣ ✅ Theme can be able to load touchy resources elsewhere, i.e. from the app in use
• 2️⃣ ✅ In that case the snapshots tests can be used but without these assets.
• 3️⃣ ✅ Users thus will be able to load their touchy resources
• 4️⃣ ✅ If well documented quite simple for users but and not costly for maintainers
• 5️⃣ ✅ Documentation not broken
• 6️⃣ ✅ No impact on tokenator
• 7️⃣ ✅ Design system toolbox app still open source

Tip

This solution is the better one.
No changes in repos, no complexity handeling more and more projects in several forges.
Touchy resources are emebed in themes libraries.
Users can simply use the theme.
Snapshots tests won't change.
Better developer experience.

Notes

Vocabulary

• "internal": in our own GitLab forge
• "external": in our GitHub repositories
• "touchy resources": fonts, icons, images under propritary licences but for which a simple mention in NOTICE is not enough
• "network": technical environmentwith proxys, DNS etc. where projects under the same can communicate / see each other
• "open source": here under OSI and FSF definitions, precisly in OUDS context with MIT license
• "public": here means not private and in GitHub
• "private": here means not public and in GitHub
• "demo app", "showcase app": the design system toolbox app
• "forge": here GitLab (internal) or GitHub
• "snapshots": snapshots tests comparing look and feels of components and tokens depending to themes
• "Brand": people defining and protecting brand guidelines and not always able to take decisions quickly and not change then

Use of fonts in internal repository

Supposing we store fonts in internal repository, i.e. the same repository as the one building the app, we can update the CI/CD chain to add the fonts in the demo app, register them and provide through TestFlight and App Store the app with the fonts.
But the issue is users can think the app reflects the lib, so the lib expose the fonts, and that's not true.

Design system toolbox migration

Steps:

• Create another repo
• Migrate the CI/CD GitHub Actions workflows to GitLab CI pipelines
• Merge with repo making the builds and releases
• Update the wiki
• Update the documentation everywhere
• Ensure there is not more repo references, even in the app
• Not be iso functional compared to Flutter, Android and web projects because their showcase apps are public

Internal touchy resources and external snapshots tests

If we have some resources internal, like fonts, which won't be versioned in public repos, we won't be able to have in GitHub Actions CI/CD snapshots tests working because not capturing the components illustrations using these touchy resources.
For the fonts, we can study if the following trick works:

• define in the documentation and API how users can laod touchy resources
• add touchy resources in the internal project building the app
• for alpha, beta and stable builds, when tests have been done, build again the design system toolbox app after having copied the touchy resources
• in the design system toolbox app, for fonts, register them if two conditions are filled: files exist and a sflags aying to not use these fonts is set to false
• in design system toolbox scheme / target, do not add this flag ; maintainers will have to copy/paste the fonts
• but in *design system toolbox snapshot / target, add the flag saying fonts must be ignored: then when running tests fonts will be always ignored whatever of they exists or not
• update the gitignore file to exclude fonts

[pylapp]

Find below 3 prooves that fonts, whatever they are, are available through website.
Preventing them to be stored in public GitHub repos even if notice about their proproetary license is a non-sense.

For Parnasse:

For Orange:

For Sosh:

[pylapp]

And attached a screenshot of our internal guidelines for ecodesign

[pylapp]

✋ Conclusion

To conclude, as discussed with @B3nz01d, solution E is choosen (E - Design system toolbox app external, theme external, touchy resources internal) for the case of Helvetica Neue 75 font for Orange themes.
The term of uses of this font do not allow to put same in open source external public repository nor put theme with a notice file saying it is propriertary.
Thus documentation of the library must say to users they must add the fonts themselves. The design system toolbox app can mebed these fonts for builds to upload after tests are done. It is acceptable to have the design system toolbox app not as a mirror of the library for this topic. It is also acceptable to have snapshot tests done on components without care of fonts.

For Sosh theme Orange owns the intellecual property.

See issue for Orange themes #965