Design systems
The Design System is the piece of The Grid that builds a webpage from page content.
A set of design systems are provided by The Grid. These use techiques like finite-domain constraint solvers, decision trees, content analysis, and polyrythmic pagination in order to produce a page which:
-
Is content driven, reflects the particular items on the page
-
Is visually pleasing, respecting the users site preferences
-
Is effective at achieving the purpose set by the user
In the future, we intent to support “plugins” which can hook into and extend existing design systems. Such plugins could build sections for particular types of data, extend content analysis or heruristics, add or modify rhythms (scoring functions).
In the meantime the daring and ambitious may implement an full design system using the mechanism below.
API
A design system is deployed as a .js
file, and runs sandboxed in a browser using JsJob.
On the server-side this is PhantomJS (with function.bind polyfill),
on client-side it runs in a WebWorker (no access to DOM).
The design system must expose a polySolvePage
function as an entry point.
window.polySolvePage = function (page, options, callback) { var html = “”; var err = null;
return callback(err, html, details);
};
The function will be called with a
Page object
containing the data to be put on the page.
The page
also includes the Site config
for the particular page.
The callback
should be called with the HTML page produced by the design system,
or an Error
object in case of failure. details
may be an object with design-system
specific information about the produced page or failure, for use in debugging and/or
machine learning.
Assets in the produced HTML page must either be inlined in the HTML (recommended for CSS, GSS), or refer to a stable URL on a HTTPS enabled CDN (recommended for fonts, images).
Use custom design system
You can configure a site to use a custom design system,
by setting the style
property to be a URL to .JS file implementing the API above.
style: https://example.net/path/mydesignsystem-0.1.0.js
It is heavily recommended that the JS is served over https. Also, we recommend that the path is strictly versioned, each new code change gets a new URL, and the configuration is updated to activate the new version.
Use config
object of the PUT /site/$id
API to change site configuration from an app.
For example, using the configure-site example to enable a
trivial design system.
thegrid-site-configure https://thegrid.ai/mysite style https://developer.thegrid.io/designsystems/original-html.js
Note: This will override the default design system completely!
To reset back to the default design system, remove the style
key/value.
Custom settings
If your design system has settings, they should be persisted in the site config. You can use the API in order to build a web app with custom user interface to let users configuring settings.
For compatibility, it is recommended that all configuration keys are prefixed with your application/design-system name.
For instance, if you have an option for ‘density’, use something like mysystem_density: 3.3
or use mysystem: { density: 3.3 }
.
All changes to site configuration will trigger a rebuild of the pages on the site.
Running locally
Assuming mypage.json
is a page input datastructure, you can execute your designsystem locally using
thegrid-designsystem-run https://developer.thegrid.io/designsystems/original-html.js mypage.json > output.html
You can now open output.html
in your browser.
You should have PhantomJS 2.x installed, and phantomjs
should existing on PATH.
This is then executed in the same way as on the production infrastructure.
Tools
Designs systems are complex beasts. In order to create them we have built a set of libraries, services and tools. Several of these are already open source:
-
Grid Style Sheets (GSS), constraint-based layout system
-
imgflo, on-demand server-side image processing. Helpers: RIG and imgflo-url
-
Grid Object Model (GOM), HTML templating and transformations
-
finitedomain, High-performance finite domain solver
-
Flowerflip, Promise-based finite-domain constraint solver
-
Regimen, Chai.js-based expectations for item/block consumption
More to be released soon!
HTTP APIs
Registered design systems ¶
A registered designsystem can be used across many sites by referring to it by name (istead of URL). Such a designsystem can have many versions, and new versions will first be pushed into staging, where pages are solved without influencing the live site. One can look at and analyze these page solutions, and once one is confident of the quality of the new version, trigger rollout to all sites with that designsystem.
If you want access to this functionality, you need an access token (secret) associated with your design system. Contact [email protected] and mark the request with ‘designsystem development’, and include your TheGrid user UUID. In the future, we may support self-service for registering new design systems.
These APIs are Webhooks signed as JSON Web Token.
Designsystem events ¶
For code examples, see thegrid-designsystem-update and thegrid-designsystem-collaborators
Registering new design system versionPOST/designsystem_event
Example URI
Headers
Content-Type: application/json
202
Setting design system collaboratorsPOST/designsystem_event
Example URI
Headers
Content-Type: application/json
202
Solutions ¶
A solution is the page output from a design system for a particular page-solving job, and associated metadata.
These APIs are authenticated with standard OAuth2 Bearer-token.
The application using them must request the designsystem_review
scope.
Permissions are granted per-designsystem, to users registered as a collaborators of the designsystem in question.
Designsystems ¶
List available designsystemsGET/designsystem
Lists designsystems you are authorized to access.
Example URI
200
Headers
Content-Type: application/json
Solutions ¶
Note that since we create multiple solution variants for one solve job,
and in future may ask user which one to publish, a solution can be succeeded: true
but published: false
.
And since user never sees or can publish staging results. staged: true
implies published: false
.
List solutionsGET/designsystem/{?site,path,version,published,staged,limit,offset}/solutions
Example URI
- site
string
(optional)Website to return results for. Ex: ‘the-domains/d4’
- path
string
(optional)Page path to return results for. Ex: “index.html” for frontpage.
- version
string
(optional)Designsystem version to return results for. Ex: “0.10.0”
- published
boolean
(optional)If true, return only solutions which were made live on a site.
- staged
boolean
(optional)If true, return only solutions produced in staging. If false, only from production.
- limit
number
(optional)Pagination limit. Defaults to 100
- offset
number
(optional)Pagination offset
200
Headers
Content-Type: application/json
Solution details ¶
Get details about a solutionGET/designsystem/solutions/
Example URI
200
Headers
Content-Type: application/json
Solution output HTML ¶
Get solution outputGET/designsystem/solutions/output
Returns the HTML produced by design system for this solution.
Example URI
200
Headers
Content-Type: text/html