Page MenuHomePhabricator

Include a mini sample project that shows use of component, CSS, Tokens
Open, Needs TriagePublic

Description

Story: I want to start using Wikit quickly. The documentation is all there, but I do not know how to use it in an actual project.

Possible solution: Provide a small, bare-bones example 'app' with the repo and/or documentation which shows:

  • A simple UI made of a few components
  • Use of design tokens (or should 'users' of the components never need to use them?)

Original proposal: https://github.com/wmde/wikit/issues/205

Event Timeline

Restricted Application added a project: Wikidata. · View Herald TranscriptOct 6 2020, 11:04 AM
Restricted Application added a subscriber: Aklapper. · View Herald Transcript
Jan_Dittrich updated the task description. (Show Details)Oct 7 2020, 8:04 AM
Jan_Dittrich added a subscriber: Jan_Dittrich.

…I did write the original issue on github, in case anyone has questions.

Responding merely as someone who took part in the initial hike and, of course, had some ideas of how things would proceed...

A simple UI made of a few components

I'm interpreting "how to use it in an actual project" as a best practice kind of place to copy from.
It always was assumption that the "Show code" link as seen e.g. on https://wmde.github.io/wikit/?path=/docs/vue_icon--all would serve this purpose. Combined with https://wmde.github.io/wikit/?path=/docs/documentation-getting-started--page#1-install-via-npm this should get a developer started.

The "Show code" links IMO unfortunately had a lot of their clarity removed when multiple stories were grouped into one (#160).

Use of design tokens (or should 'users' of the components never need to use them?)

I assume that many/most applications will not exclusively be built from ready-made wikit components but will need some additional ones (maybe to be upstreamed at some point in the future) or add some skeleton around them which should have a similar flavor no less - so I assume that most applications will have a need for tokens on top of components (even when wikit is in a much more "complete" state than now). How to get to them is documented here: https://wmde.github.io/wikit/?path=/docs/documentation-getting-started--page#using-tokens

Pointers how we could make this more approachable are very welcome.

It always was assumption that the "Show code" link…

I think it would be helpful to see how several of the components can be combined

I am also unsure about the code shown… I never used vue components this way (function normal(): Component {). Is this typescript/ a typescript way of doing it?

Maybe the language used in the examples is something that should be pointed out in the "getting started" or at the examples themselves. Similarly, the project seems to assume webpack (?) which also could be pointed out.

How to get to them is documented here: https://wmde.github.io/wikit/?path=/docs/documentation-getting-started--page#using-tokens

I think also here it would be good to have an example of using tokens.

I think it would be helpful to see how several of the components can be combined

Agree. That, in my eyes, could be the job of dedicated stories. I see this happening eventually once it becomes more relevant with the advent of more components.

I am also unsure about the code shown

Agree. I think the vehicle of "Show code" and its placement makes sense, but what it shows could be reduced to avoid confusion (cf. 1).
tl;dr only the template bit is relevant. I don't feel like I'm in a position to file a ticket to request changes around that but it would make sense to me.

I think also here it would be good to have an example of using tokens.

What you mean is clear but any concrete example exhibits the problem that it would showcase (and thus, arguably, favor) the use of one particular technology - while the documentation so far intentionally tries to avoid that: the tokens are shipped in multiple formats (less, sass, css, json) exactly to enable users of all technologies alike.
I actually once created a commit to be a bit more helpful without pushing a particular tech - but it never saw the light of day. Do you think it would be helpful at all/a step in the right direction?

What you mean is clear but any concrete example exhibits the problem that it would showcase (and thus, arguably, favor) the use of one particular technology

I think that this kind of neutrality is not very helpful beyond the claim of neutrality itself; even a LESS-writing person will benefit from a SASS example.

Prio Notes:

  • This seems like a nice to have task, we were wondering whether this project perhaps belongs in a prototype week or day.
  • As the amount of effort seems relatively high for the desired impact, we might need to consider breaking this task down further.
  • This project will be revisited later on when there are less issues on the DS backlog